cloudflare-turnstile-rails 0.8.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '087645e721fc666c38e61d1ec636da847d0d4066b364fe0cfbcaed4d7a080559'
+  data.tar.gz: 334e358ee80c3ddc22a020b3646db47d7b9e1b91afb2319240364275822b58ce
+SHA512:
+  metadata.gz: 64f54d13d40a27a65eaafb793a6bfb0e70cfdce39aba24f057a171a618f00899ed01a32aacc32c5ac8f9cbea58a2e44649a3e446eadfe6c966654a9611abd3c0
+  data.tar.gz: dcabd769cc15cd4945f5ef42bdf1bb29038eb581fd88531f3b3f5838ad7e9e25e234071e889792c8f921221a1a1ca1e69a4a0ac4bc7346d743a9e92eabf415b4

data/.rubocop.yml

@@ -0,0 +1,32 @@
+plugins:
+  - rubocop-md
+  - rubocop-minitest
+  - rubocop-performance
+  - rubocop-rake
+
+AllCops:
+  TargetRubyVersion: 2.6.0
+  NewCops: enable
+  Exclude:
+    - .git/**/*
+    - vendor/bundle/**/*
+
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - cloudflare-turnstile-rails.gemspec
+
+Layout/SpaceInsideHashLiteralBraces:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 12
+
+Minitest/MultipleAssertions:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  EnforcedStyle: never

data/Appraisals

@@ -0,0 +1,65 @@
+appraise 'rails-5.0' do
+  gem 'rails', '~> 5.0.0'
+  if RUBY_VERSION >= '3.4.0'
+    gem 'base64'
+    gem 'mutex_m'
+  end
+end
+
+appraise 'rails-5.1' do
+  gem 'rails', '~> 5.1.0'
+  if RUBY_VERSION >= '3.4.0'
+    gem 'base64'
+    gem 'mutex_m'
+  end
+end
+
+appraise 'rails-5.2' do
+  gem 'rails', '~> 5.2.0'
+  if RUBY_VERSION >= '3.4.0'
+    gem 'base64'
+    gem 'mutex_m'
+  end
+end
+
+appraise 'rails-6.0' do
+  gem 'rails', '~> 6.0.0'
+  if RUBY_VERSION >= '3.4.0'
+    gem 'drb'
+    gem 'mutex_m'
+  end
+end
+
+appraise 'rails-6.1' do
+  gem 'rails', '~> 6.1.0'
+  if RUBY_VERSION >= '3.4.0'
+    gem 'drb'
+    gem 'mutex_m'
+  end
+end
+
+if RUBY_VERSION >= '2.7.0'
+  appraise 'rails-7.0' do
+    gem 'rails', '~> 7.0.0'
+    if RUBY_VERSION >= '3.4.0'
+      gem 'drb'
+      gem 'mutex_m'
+    end
+  end
+
+  appraise 'rails-7.1' do
+    gem 'rails', '~> 7.1.0'
+  end
+end
+
+if RUBY_VERSION >= '3.1.0'
+  appraise 'rails-7.2' do
+    gem 'rails', '~> 7.2.0'
+  end
+end
+
+if RUBY_VERSION >= '3.2.0'
+  appraise 'rails-8.0' do
+    gem 'rails', '~> 8.0.0'
+  end
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Vadim Kononov
+
+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

@@ -0,0 +1,249 @@
+# Cloudflare Turnstile Rails
+
+[![Gem Version](https://badge.fury.io/rb/cloudflare-turnstile-rails.svg)](https://rubygems.org/gems/cloudflare-turnstile-rails)
+[![Lint Status](https://github.com/vkononov/cloudflare-turnstile-rails/actions/workflows/lint.yml/badge.svg)](https://github.com/vkononov/cloudflare-turnstile-rails/actions/workflows/lint.yml)
+[![Test Status](https://github.com/vkononov/cloudflare-turnstile-rails/actions/workflows/test.yml/badge.svg)](https://github.com/vkononov/cloudflare-turnstile-rails/actions/workflows/test.yml)
+
+A lightweight Rails helper for effortless Cloudflare Turnstile integration with Turbo support and CSP compliance.
+
+## Features
+
+* **One‑line integration**: `<%= cloudflare_turnstile_tag %>` in views, `verify_turnstile(model:)` in controllers — no extra wiring.
+* **CSP nonce support**: Honors Rails’s `content_security_policy_nonce` for secure inline scripts.
+* **Turbo & Turbo Streams aware**: Automatically re‑initializes widgets on `turbo:load`, `turbo:before-stream-render`, and DOM mutations.
+* **Error‑code mappings**: Human‑friendly messages for Cloudflare’s test keys and common failure codes.
+* **Rails Engine & Asset pipeline**: Ships a precompiled JS helper via Railtie — no manual asset setup.
+* **Lightweight**: Pure Ruby/Rails with only `net/http` and `json` dependencies.
+
+> **Note:** Even legacy Rails applications (5+) can leverage Cloudflare Turnstile by adding this gem.
+
+## Getting Started
+
+### Prerequisites
+
+Before you begin, you should have your own Cloudflare Turnstile keys:
+
+- **Site Key** and **Secret Key** from Cloudflare.
+
+> Cloudflare provides extensive documentation for Turnstile [here](https://developers.cloudflare.com/turnstile/). It is highly recommended to read it to understand its options and idiosyncrasies.
+
+### Installation
+
+Add the gem to your Gemfile and bundle:
+
+```ruby
+gem 'cloudflare-turnstile-rails'
+```
+
+```bash
+bundle install
+```
+
+Generate the default initializer:
+
+```bash
+bin/rails generate cloudflare_turnstile:install
+```
+
+Configure your **Site Key** and **Secret Key** in `config/initializers/cloudflare_turnstile.rb`:
+
+```ruby
+Cloudflare::Turnstile::Rails.configure do |config|
+  # Set your Cloudflare Turnstile Site Key and Secret Key.
+  config.site_key   = ENV.fetch('CLOUDFLARE_TURNSTILE_SITE_KEY', nil)
+  config.secret_key = ENV.fetch('CLOUDFLARE_TURNSTILE_SECRET_KEY', nil)
+
+  # Optional: Append render or onload query params
+  # config.render = 'explicit'
+  # config.onload = 'onloadMyCallback'
+end
+```
+
+### Frontend Integration
+
+> The helper injects the Turnstile widget and accompanying JavaScript inline by default (honoring Rails' `content_security_policy_nonce`), so there's no need to allow `unsafe-inline` in your CSP.
+
+Include the widget in your views or forms:
+
+```erb
+<%= cloudflare_turnstile_tag %>
+```
+
+However, it is recommended to match your `theme` and `language` to your app’s design and locale. You can do this by passing `data` attributes to the helper:
+
+```erb
+<%= cloudflare_turnstile_tag data: { theme: 'auto', language: 'en' } %>
+```
+
+* For all available **data-**\* options (e.g., `action`, `cdata`, `theme`, etc.), refer to the official Cloudflare client-side rendering docs:
+  [https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/#configurations](https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/#configurations)
+* **Supported locales** for the widget UI can be found here:
+  [https://developers.cloudflare.com/turnstile/reference/supported-languages/](https://developers.cloudflare.com/turnstile/reference/supported-languages/)
+
+### Backend Validation
+
+In your controller, call:
+
+```ruby
+if verify_turnstile(model: @user)
+  # success → returns a VerificationResponse object
+else
+  # failure → returns false and adds errors to `@user`
+  render :new, status: :unprocessable_entity
+end
+```
+
+* In addition to the `model` option, you can pass any **siteverify** parameters (e.g., `secret`, `remoteip`, `idempotency_key`) supported by Cloudflare’s server-side validation API:
+  [https://developers.cloudflare.com/turnstile/get-started/server-side-validation/#accepted-parameters](https://developers.cloudflare.com/turnstile/get-started/server-side-validation/#accepted-parameters)
+
+* On success, `verify_turnstile` returns a `VerificationResponse` (with methods like `.success?`, `.errors`, `.action`, `.cdata`), so you can inspect frontend-set values (`data-action`, `data-cdata`, etc.). On failure it returns `false` and adds a validation error to your model (if provided).
+
+### Turbo & Turbo Streams Support
+
+All widgets will re‑initialize automatically on full and soft navigations (`turbo:load`), on `<turbo-stream>` renders (`turbo:before-stream-render`), and on DOM mutations — no extra wiring needed.
+
+### Turbolinks Support
+
+If your Rails app still uses Turbolinks (rather than Turbo), you can add a small helper to your JavaScript pack so that remote form submissions returning HTML correctly display validation errors without a full page reload. Simply copy the file:
+
+```
+templates / shared / cloudflare_turbolinks_ajax_cache.js
+```
+
+into your application’s JavaScript entrypoint (for example `app/javascript/packs/application.js`). This script listens for Rails UJS `ajax:complete` events that return HTML, caches the response as a Turbolinks snapshot, and then restores it via `Turbolinks.visit`, ensuring forms with validation errors are re‑rendered seamlessly.
+
+## Testing Your Integration
+
+Cloudflare provides dummy sitekeys and secret keys for development and testing. You can use these to simulate every possible outcome of a Turnstile challenge without touching your production configuration. For future updates, see [https://developers.cloudflare.com/turnstile/troubleshooting/testing/](https://developers.cloudflare.com/turnstile/troubleshooting/testing/).
+
+### Dummy Sitekeys
+
+| Sitekey                    | Description                     | Visibility |
+|----------------------------|---------------------------------|------------|
+| `1x00000000000000000000AA` | Always passes                   | visible    |
+| `2x00000000000000000000AB` | Always blocks                   | visible    |
+| `1x00000000000000000000BB` | Always passes                   | invisible  |
+| `2x00000000000000000000BB` | Always blocks                   | invisible  |
+| `3x00000000000000000000FF` | Forces an interactive challenge | visible    |
+
+### Dummy Secret Keys
+
+| Secret key                            | Description                          |
+|---------------------------------------|--------------------------------------|
+| `1x0000000000000000000000000000000AA` | Always passes                        |
+| `2x0000000000000000000000000000000AA` | Always fails                         |
+| `3x0000000000000000000000000000000AA` | Yields a "token already spent" error |
+
+Use these dummy values in your **development** environment to verify all flows. Ensure you match a dummy secret key with its corresponding sitekey when calling `verify_turnstile`. Development tokens will look like `XXXX.DUMMY.TOKEN.XXXX`.
+
+## Upgrade Guide
+
+This gem is fully compatible with Rails **5.0 and above**, and no special upgrade steps are required:
+
+* **Simply update Rails** in your application as usual.
+* Continue using the same `cloudflare_turnstile_tag` helper in your views and `verify_turnstile` in your controllers.
+* All Turbo, Turbo Streams, and Turbolinks integrations continue to work without changes.
+
+If you run into any issues after upgrading Rails, please [open an issue](https://github.com/vkononov/cloudflare-turnstile-rails/issues) so we can address it promptly.
+
+## Troubleshooting
+
+**Duplicate Widgets**
+- If more than one Turnstile widget appears in the same container, this indicates a bug in the gem—please [open an issue](https://github.com/vkononov/cloudflare-turnstile-rails/issues) so it can be addressed.
+
+**Explicit Rendering**
+- If you’ve configured explicit mode (`config.render = 'explicit'` or `cloudflare_turnstile_tag render: 'explicit'`) but widgets still auto-render, override the default container class:
+
+  ```erb
+  <%= cloudflare_turnstile_tag class: nil %>
+  ```
+
+  or
+
+  ```erb
+  <%= cloudflare_turnstile_tag class: 'my-widget-class' %>
+  ```
+
+- By default Turnstile targets elements with the `cf-turnstile` class. For more details, see Cloudflare’s [https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/#explicitly-render-the-turnstile-widget](https://developers.cloudflare.com/turnstile/get-started/client-side-rendering/#explicitly-render-the-turnstile-widget).
+
+**CSP Nonce Issues**
+- When using Rails’ CSP nonces, make sure `content_security_policy_nonce` is available in your view context — otherwise the Turnstile script may be blocked.
+
+**Server Validation Errors**
+- Validation failures (invalid, expired, or already‑used tokens) surface as model errors. Consult Cloudflare’s [server-side troubleshooting](https://developers.cloudflare.com/turnstile/troubleshooting/testing/) for common error codes and test keys.
+
+> Still stuck? Check the Cloudflare Turnstile docs: [https://developers.cloudflare.com/turnstile/get-started/](https://developers.cloudflare.com/turnstile/get-started/)
+
+## Development
+
+### Setup
+
+Install dependencies, linters, and prepare everything in one step:
+
+```bash
+bin/setup
+```
+
+### Running the Test Suite
+
+[Appraisal](https://github.com/thoughtbot/appraisal) is used to run the full test suite against multiple Rails versions by generating separate Gemfiles and isolating each environment. To install dependencies and exercise all unit, integration and system tests:
+
+Execute **all** tests (unit, integration, system) across every Ruby & Rails combination:
+
+```bash
+bundle exec appraisal install
+bundle exec appraisal rake test
+```
+
+> **CI Note:** Our GitHub Actions [.github/workflows/test.yml](https://github.com/vkononov/cloudflare-turnstile-rails/blob/main/.github/workflows/test.yml) runs this command on each Ruby/Rails combo and captures screenshots from system specs.
+
+### Code Linting
+
+Enforce code style with RuboCop (latest Ruby only)::
+
+```bash
+bundle exec rubocop
+```
+
+> **CI Note:** We run this via [.github/workflows/lint.yml](https://github.com/vkononov/cloudflare-turnstile-rails/blob/main/.github/workflows/lint.yml) on the latest Ruby only.
+
+### Generating Rails Apps Locally
+
+To replicate the integration examples on your machine, you can generate a Rails app directly from the template:
+
+```bash
+rails new test_app \
+  --skip-git --skip-action-mailer --skip-active-record \
+  --skip-action-cable --skip-sprockets --skip-javascript \
+  -m templates/template.rb
+```
+
+Get the exact command from the `test/integration/` folder, where each integration test has a corresponding Rails app template. For example, to replicate the `test/integration/rails7.rb` test for Rails `v7.0.4`, run:
+
+```bash
+gem install rails -v 7_0_4
+
+rails _7_0_4_ new test_app \
+  --skip-git --skip-keeps \
+  --skip-action-mailer --skip-action-mailbox --skip-action-text \
+  --skip-active-record --skip-active-job --skip-active-storage \
+  --skip-action-cable --skip-jbuilder --skip-bootsnap --skip-api \
+  -m test/integration/rails_7_0_4.rb
+```
+
+Then:
+
+```bash
+cd test_app
+bin/rails server
+```
+
+This bootstraps an app preconfigured for Cloudflare Turnstile matching the versions under `test/integration/`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/vkononov/cloudflare-turnstile-rails.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler/gem_tasks'
+require 'minitest/test_task'
+
+Minitest::TestTask.create
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/cloudflare/turnstile/rails/assets/javascripts/cloudflare_turnstile_helper.js

@@ -0,0 +1,40 @@
+(function(){
+    function reinitializeTurnstile() {
+        if (typeof turnstile !== "undefined") {
+            document.querySelectorAll('.cf-turnstile').forEach(function(el) {
+                if (!el.dataset.initialized && el.childElementCount === 0) {
+                    turnstile.render(el);
+                    el.dataset.initialized = true;
+                }
+            });
+        }
+    }
+
+    if (!window._turnstileHelperLoaded) {
+        window._turnstileHelperLoaded = true;
+
+        // read our data-attribute to know which CF script URL to use:
+        var me      = document.currentScript;
+        var cfUrl   = me.getAttribute('data-script-url');
+        var helper  = document.createElement('script');
+        helper.src  = cfUrl;
+        helper.async = true;
+        helper.defer = true;
+        var nonce   = me.getAttribute('nonce');
+        if (nonce) helper.nonce = nonce;
+        document.head.appendChild(helper);
+
+        // set up Turbo hooks only once
+        document.addEventListener("turbo:load",   reinitializeTurnstile);
+        document.addEventListener("turbo:before-stream-render", function(event) {
+            var orig = event.detail.render.bind(event.detail);
+            event.detail.render = function() {
+                orig.apply(this, arguments);
+                reinitializeTurnstile();
+            };
+        });
+    }
+
+    // always try to render any containers already in the DOM
+    reinitializeTurnstile();
+})();

data/lib/cloudflare/turnstile/rails/configuration.rb

@@ -0,0 +1,41 @@
+module Cloudflare
+  module Turnstile
+    module Rails
+      class Configuration
+        attr_writer :script_url
+        attr_accessor :site_key, :secret_key, :render, :onload
+
+        def initialize
+          @script_url = Cloudflare::SCRIPT_URL
+          @site_key = nil
+          @secret_key = nil
+          @render = nil
+          @onload = nil
+        end
+
+        # Dynamically build the URL every time, so that
+        # config.render and config.onload applied after init take effect.
+        def script_url
+          return @script_url unless @script_url == Cloudflare::SCRIPT_URL
+
+          # Otherwise, append render/onload if present:
+          params = []
+          params << "render=#{CGI.escape(@render)}" unless @render.nil?
+          params << "onload=#{CGI.escape(@onload)}" unless @onload.nil?
+
+          params.empty? ? Cloudflare::SCRIPT_URL : "#{Cloudflare::SCRIPT_URL}?#{params.join('&')}"
+        end
+
+        def validate!
+          if site_key.nil? || site_key.strip.empty?
+            raise ConfigurationError, 'Cloudflare Turnstile site_key is not set.'
+          end
+
+          return unless secret_key.nil? || secret_key.strip.empty?
+
+          raise ConfigurationError, 'Cloudflare Turnstile secret_key is not set.'
+        end
+      end
+    end
+  end
+end

data/lib/cloudflare/turnstile/rails/constants/cloudflare.rb

@@ -0,0 +1,19 @@
+module Cloudflare
+  module Turnstile
+    module Rails
+      module Cloudflare
+        # Client-side script for rendering Turnstile widgets
+        SCRIPT_URL = 'https://challenges.cloudflare.com/turnstile/v0/api.js'.freeze
+
+        # Server-side endpoint for verifying Turnstile tokens
+        SITE_VERIFY_URL = 'https://challenges.cloudflare.com/turnstile/v0/siteverify'.freeze
+
+        # Default hidden input field name for Turnstile token submission
+        RESPONSE_FIELD_NAME = 'cf-turnstile-response'.freeze
+
+        # Default CSS class applied to Turnstile widget containers
+        WIDGET_CLASS = 'cf-turnstile'.freeze
+      end
+    end
+  end
+end

data/lib/cloudflare/turnstile/rails/constants/error_codes.rb

@@ -0,0 +1,27 @@
+module Cloudflare
+  module Turnstile
+    module Rails
+      module ErrorCodes
+        # https://developers.cloudflare.com/turnstile/get-started/server-side-validation/#error-codes
+
+        MISSING_INPUT_SECRET = 'missing-input-secret'.freeze
+        INVALID_INPUT_SECRET = 'invalid-input-secret'.freeze
+        MISSING_INPUT_RESPONSE = 'missing-input-response'.freeze
+        INVALID_INPUT_RESPONSE = 'invalid-input-response'.freeze
+        BAD_REQUEST = 'bad-request'.freeze
+        TIMEOUT_OR_DUPLICATE = 'timeout-or-duplicate'.freeze
+        INTERNAL_ERROR = 'internal-error'.freeze
+
+        ALL = [
+          MISSING_INPUT_SECRET,
+          INVALID_INPUT_SECRET,
+          MISSING_INPUT_RESPONSE,
+          INVALID_INPUT_RESPONSE,
+          BAD_REQUEST,
+          TIMEOUT_OR_DUPLICATE,
+          INTERNAL_ERROR
+        ].freeze
+      end
+    end
+  end
+end

data/lib/cloudflare/turnstile/rails/constants/error_messages.rb

@@ -0,0 +1,22 @@
+require_relative 'error_codes'
+
+module Cloudflare
+  module Turnstile
+    module Rails
+      module ErrorMessages
+        MAP = {
+          ErrorCodes::TIMEOUT_OR_DUPLICATE => 'Turnstile token has already been used or expired.',
+          ErrorCodes::INVALID_INPUT_RESPONSE => 'Turnstile token is invalid.',
+          ErrorCodes::MISSING_INPUT_RESPONSE => 'Turnstile response was missing.',
+          ErrorCodes::BAD_REQUEST => 'Bad request to Turnstile verification API.',
+          ErrorCodes::INTERNAL_ERROR => 'Internal error at Turnstile. Please try again.',
+          ErrorCodes::MISSING_INPUT_SECRET => 'Server misconfiguration: Turnstile secret key missing.',
+          ErrorCodes::INVALID_INPUT_SECRET => 'Server misconfiguration: Turnstile secret key invalid.'
+        }.freeze
+
+        DEFAULT_MESSAGE = "We could verify that you're human. Please try again.".freeze
+        MISSING_TOKEN_MESSAGE = 'Cloudflare Turnstile verification missing.'.freeze
+      end
+    end
+  end
+end

data/lib/cloudflare/turnstile/rails/controller_methods.rb

@@ -0,0 +1,37 @@
+require_relative 'constants/cloudflare'
+require_relative 'constants/error_messages'
+require_relative 'verification'
+
+module Cloudflare
+  module Turnstile
+    module Rails
+      module ControllerMethods
+        def verify_turnstile(model: nil, secret: nil, response: nil, remoteip: nil, idempotency_key: nil) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength
+          response ||= params[Cloudflare::RESPONSE_FIELD_NAME]
+
+          if response.nil? || response.strip.empty?
+            error_message = ErrorMessages::MISSING_TOKEN_MESSAGE
+            model&.errors&.add(:base, error_message)
+            return false
+          end
+
+          result = Rails::Verification.verify(
+            secret: secret,
+            response: response,
+            remoteip: remoteip,
+            idempotency_key: idempotency_key
+          )
+
+          unless result.success?
+            error_code = result.errors.first
+            error_message = ErrorMessages::MAP.fetch(error_code, ErrorMessages::DEFAULT_MESSAGE)
+            model&.errors&.add(:base, error_message)
+            return false
+          end
+
+          result
+        end
+      end
+    end
+  end
+end

data/lib/cloudflare/turnstile/rails/engine.rb

@@ -0,0 +1,17 @@
+module Cloudflare
+  module Turnstile
+    module Rails
+      class Engine < ::Rails::Engine
+        engine_name 'cloudflare_turnstile_rails'
+
+        initializer 'cloudflare_turnstile.assets' do |app|
+          js_path = ::Cloudflare::Turnstile::Rails::Engine.root.join(
+            'lib', 'cloudflare', 'turnstile', 'rails', 'assets', 'javascripts'
+          )
+          app.config.assets.paths << js_path
+          app.config.assets.precompile += %w[cloudflare_turnstile_helper.js]
+        end
+      end
+    end
+  end
+end

data/lib/cloudflare/turnstile/rails/helpers.rb

@@ -0,0 +1,35 @@
+require_relative 'constants/cloudflare'
+
+module Cloudflare
+  module Turnstile
+    module Rails
+      module Helpers
+        def cloudflare_turnstile_tag(site_key: nil, include_script: true, **html_options) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+          site_key ||= Rails.configuration.site_key
+          Rails.configuration.validate!
+
+          html_options[:class] = Cloudflare::WIDGET_CLASS unless html_options.key?(:class)
+          html_options[:data] ||= {}
+          html_options[:data][:sitekey] ||= site_key
+
+          script_tag = nil
+          if include_script && !@_ct_helper_rendered
+            @_ct_helper_rendered = true
+
+            # Emit exactly one tag:
+            script_tag = javascript_include_tag(
+              'cloudflare_turnstile_helper',
+              async: true,
+              defer: true,
+              nonce: (defined?(content_security_policy_nonce) ? content_security_policy_nonce : nil),
+              data: { 'script-url': Rails.configuration.script_url }
+            )
+          end
+
+          widget = content_tag(:div, '', html_options)
+          safe_join([script_tag, widget].compact, "\n")
+        end
+      end
+    end
+  end
+end

data/lib/cloudflare/turnstile/rails/railtie.rb

@@ -0,0 +1,22 @@
+require_relative 'controller_methods'
+require_relative 'helpers'
+
+module Cloudflare
+  module Turnstile
+    module Rails
+      class Railtie < ::Rails::Railtie
+        initializer 'cloudflare.turnstile.rails.controller_methods' do
+          ActiveSupport.on_load(:action_controller) do
+            include Rails::ControllerMethods
+          end
+        end
+
+        initializer 'cloudflare.turnstile.rails.helpers' do
+          ActiveSupport.on_load(:action_view) do
+            include Rails::Helpers
+          end
+        end
+      end
+    end
+  end
+end