verify_human 0.1.5

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0b8f03bb8489d979c45ce89d32a7060cddad065f4e10519c3e66a83349855076
+  data.tar.gz: aab710a58a80595c172ecf3587e398e7ea3295570e052b8fc68a2ff11d5cd163
+SHA512:
+  metadata.gz: 48d7bdce8bd369f27077241dcb8fee2118cae1575ea1fb38de40e5b102da1d8984c83ab86e8e7f96209255370b69871f43cade994e5ad219945e6fea005baf38
+  data.tar.gz: 5634039ac132fc72b2e57185a259e1159f496527a09661699133b2f118270a4dd8a1188949166a7c3a4f78e309f820cd06f2cee617855765ab6cefeae582f935

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marc Köhlbrugge
+
+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,89 @@
+# verify_human
+
+Human verification for Rails forms. Cloudflare Turnstile under the hood; provider-agnostic API on the surface.
+
+This is an opinionated gem: it does human verification the way I like it in my own Rails apps. It's shared in case that way suits you too, not as a general-purpose library that tries to fit every setup.
+
+## Installation
+
+```ruby
+gem "verify_human"
+```
+
+## Usage
+
+```ruby
+# ApplicationController (or a specific controller)
+include HumanVerification
+
+# Any controller with a form bots abuse. Guards :create by default;
+# declare AFTER rate_limit so the cheap local check runs first.
+rate_limit to: 5, within: 15.minutes, only: :create
+verify_human "sign_in"
+```
+
+```erb
+<%# In the form. Invisible for ~98% of visitors (interaction-only Managed
+    widget); shows a one-click checkbox only when Cloudflare requires it. %>
+<%= human_verification_tag "sign_in" %>
+
+<%# Submit the surrounding form as soon as a token is issued: %>
+<%= human_verification_tag "apply", auto_submit: true %>
+
+<%# Never show UI at all (separate invisible-mode widget; visitors who can't
+    pass silently post tokenless -- pair with a retry/interstitial flow): %>
+<%= human_verification_tag "apply", invisible: true %>
+```
+
+Override the failure response per controller (default: `redirect_back` with an alert):
+
+```ruby
+def human_verification_failed
+  flash.now[:alert] = "We couldn't verify you're human. Please try again."
+  render :new, status: :unprocessable_entity  # frame-safe, preserves input
+end
+```
+
+## Configuration
+
+Reads Rails credentials; verification no-ops unless BOTH keys are present (dev/test are zero-config):
+
+```yaml
+turnstile:
+  site_key: ...
+  secret_key: ...
+  invisible_site_key: ...    # only if you use invisible: true
+  invisible_secret_key: ...
+```
+
+Create Managed-mode (and optionally invisible-mode) widgets in the Cloudflare dashboard or via API. Development can use Cloudflare's always-pass test keys. Invisible mode requires referencing Cloudflare's Turnstile Privacy Addendum in your privacy policy.
+
+## Behavior worth knowing
+
+- Fails open on Cloudflare outages (2s/3s timeouts, under a 20s rack-timeout budget); a blank token is rejected without an HTTP call.
+- The siteverify `action` is enforced per form name: a token minted on one widget can't be spent on another endpoint.
+- The Stimulus controller is Turbo-safe: container cleared around Turbo caching (TurnstileError 300030), script-load `onerror` recovery, no render-after-disconnect, and a fresh widget after a Turbo morph (e.g. a form re-rendered with 422 on a page using `turbo_refreshes_with method: :morph`).
+- Users who block challenges.cloudflare.com cannot pass (fail closed by nature of CAPTCHAs) -- keep failure paths friendly.
+
+## Tests
+
+```ruby
+require "verify_human/test_helpers"   # needs WebMock
+
+include HumanVerification::TestHelpers
+with_human_verification_configured { ... }
+stub_human_verification(success: true, action: "sign_in")
+stub_human_verification_outage
+```
+
+## Contributing
+
+Bug reports are welcome as [GitHub issues](https://github.com/marckohlbrugge/verify_human/issues). I don't accept pull requests: the gem stays as opinionated as it is, so please fork it if you want it to work differently.
+
+## Releasing
+
+Bump `VerifyHuman::VERSION`, tag `vX.Y.Z`, push the tag. GitHub Actions publishes to rubygems.org as a trusted publisher, so no API key is stored anywhere.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/app/assets/javascripts/verify_human/turnstile_controller.js

@@ -0,0 +1,90 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Renders a Cloudflare Turnstile widget. Invisible for most visitors
+// (appearance: interaction-only); only shows a checkbox when Cloudflare
+// requires interaction. With autoSubmit, the surrounding form is submitted
+// as soon as a token is issued.
+let scriptPromise
+
+function loadTurnstile() {
+  if (window.turnstile) return Promise.resolve()
+
+  scriptPromise ||= new Promise((resolve) => {
+    const script = document.createElement("script")
+    script.src = "https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit"
+    script.async = true
+    script.onload = resolve
+    script.onerror = () => {
+      // Clear the memoized promise so a later connect() can retry, and resolve
+      // so awaiting controllers proceed (render is guarded on window.turnstile).
+      scriptPromise = undefined
+      resolve()
+    }
+    document.head.appendChild(script)
+  })
+
+  return scriptPromise
+}
+
+export default class extends Controller {
+  static values = { siteKey: String, action: String, autoSubmit: Boolean }
+
+  connect() {
+    this.disconnected = false
+    // Turbo must never snapshot a rendered widget: restoring one leaves stale
+    // iframe markup in the container, and rendering into a non-empty container
+    // crashes the widget (TurnstileError 300030, no token ever minted).
+    this.clearBeforeCache = () => this.reset()
+    document.addEventListener("turbo:before-cache", this.clearBeforeCache)
+
+    // A Turbo morph (page refresh, or a form re-rendered with 422 on a page
+    // using turbo_refreshes_with :morph) strips the widget's markup but keeps
+    // this controller connected, and the token it held is already spent.
+    this.renderAfterMorph = (event) => {
+      if (event.target === this.element) this.render()
+    }
+    this.element.addEventListener("turbo:morph-element", this.renderAfterMorph)
+
+    this.render()
+  }
+
+  disconnect() {
+    this.disconnected = true
+    document.removeEventListener("turbo:before-cache", this.clearBeforeCache)
+    this.element.removeEventListener("turbo:morph-element", this.renderAfterMorph)
+    this.reset()
+  }
+
+  async render() {
+    await loadTurnstile()
+    if (this.disconnected || !window.turnstile) return
+
+    this.reset() // defense against an already-cached snapshot or a morphed container
+    this.widgetId = window.turnstile.render(this.element, {
+      sitekey: this.siteKeyValue,
+      action: this.actionValue,
+      appearance: "interaction-only",
+      "response-field-name": "cf_turnstile_response",
+      callback: () => this.tokenReceived(),
+      // A crashed widget can't mint a token; reset so the form stays usable
+      // and the server-side retry flow takes over on submit.
+      "error-callback": () => {
+        this.reset()
+        return true
+      }
+    })
+  }
+
+  tokenReceived() {
+    if (this.disconnected) return
+    if (this.autoSubmitValue) this.element.closest("form")?.requestSubmit()
+  }
+
+  reset() {
+    if (this.widgetId) {
+      window.turnstile.remove(this.widgetId)
+      this.widgetId = null
+    }
+    this.element.replaceChildren()
+  }
+}

data/app/controllers/concerns/human_verification.rb

@@ -0,0 +1,69 @@
+module HumanVerification
+  extend ActiveSupport::Concern
+
+  VERIFY_URL = "https://challenges.cloudflare.com/turnstile/v0/siteverify"
+
+  class_methods do
+    # Declare after any rate_limit so the cheap local check runs first.
+    # Guards :create by default -- the public form submissions bots abuse.
+    # Pass only:/except: to protect other actions (their forms need a widget).
+    def verify_human(name = nil, **options)
+      options[:only] = :create unless options.key?(:only) || options.key?(:except)
+      before_action(**options) { verify_turnstile(name) }
+    end
+  end
+
+  private
+
+  def verify_turnstile(expected_name = nil)
+    return unless human_verification_enabled?
+    return if turnstile_token_valid?(expected_name)
+
+    human_verification_failed
+  end
+
+  # Override in controllers that need a custom failure response (e.g. forms
+  # inside a turbo frame, where a redirect yields "Content missing" and
+  # discards the user's input).
+  def human_verification_failed
+    redirect_back fallback_location: root_path,
+      alert: "We couldn't verify you're human. Please try again."
+  end
+
+  # Both keys or nothing: enforcing with only a secret_key would reject every
+  # submission, because human_verification_tag renders no widget without a site_key.
+  # (HumanVerificationHelper duplicates this check for view code.)
+  def human_verification_enabled?
+    %i[site_key secret_key].all? { |key| Rails.application.credentials.dig(:turnstile, key).present? }
+  end
+
+  # Tokens are widget-specific: a page may run the invisible-mode widget while
+  # other forms run the managed one. The form says which one minted the token
+  # (spoofing the param just fails verification against the wrong secret).
+  def turnstile_secret_key
+    key = (params[:cf_turnstile_widget] == "invisible") ? :invisible_secret_key : :secret_key
+    Rails.application.credentials.dig(:turnstile, key)
+  end
+
+  def turnstile_token_valid?(expected_name)
+    return false if params[:cf_turnstile_response].blank?
+
+    response = Faraday.post(VERIFY_URL,
+      secret: turnstile_secret_key,
+      response: params[:cf_turnstile_response],
+      remoteip: request.remote_ip) do |req|
+      # Well under rack-timeout's 20s budget, so a slow Cloudflare fails open
+      # via the rescue below instead of 500ing the request.
+      req.options.open_timeout = 2
+      req.options.timeout = 3
+    end
+
+    # Cloudflare calls the per-widget name "action" in its API. Its testing
+    # keys (development) answer without one, flagged in the metadata.
+    data = JSON.parse(response.body)
+    data["success"] && (expected_name.nil? || data["action"] == expected_name || data.dig("metadata", "result_with_testing_key") == true)
+  rescue Faraday::Error, JSON::ParserError => error
+    Rails.error.report(error)
+    true # Fail open: never lock users out because Cloudflare is unreachable
+  end
+end

data/app/helpers/human_verification_helper.rb

@@ -0,0 +1,28 @@
+module HumanVerificationHelper
+  # Renders nothing when no site key is configured (development/test).
+  # With auto_submit: true the surrounding form is submitted as soon as
+  # Cloudflare issues a token.
+  # With invisible: true, an invisible-mode widget runs instead: it never
+  # shows UI, and when it cannot pass silently the form simply posts without
+  # a token and the app's failure path takes over. The paired hidden field tells
+  # the server which widget's secret to verify against.
+  def human_verification_tag(name = nil, auto_submit: false, invisible: false, **options)
+    return unless human_verification_enabled?
+
+    widget = tag.div(**options, data: {
+      controller: "turnstile",
+      turnstile_site_key_value: Rails.application.credentials.dig(:turnstile, invisible ? :invisible_site_key : :site_key),
+      turnstile_action_value: name,
+      turnstile_auto_submit_value: auto_submit
+    })
+    invisible ? widget + hidden_field_tag(:cf_turnstile_widget, "invisible") : widget
+  end
+
+  # Both keys or nothing, matching HumanVerification#human_verification_enabled?
+  # (intentionally the same name): rendering a widget without a secret_key
+  # would collect tokens the server never checks, and enforcing without a
+  # site_key would reject every submission.
+  def human_verification_enabled?
+    %i[site_key secret_key].all? { |key| Rails.application.credentials.dig(:turnstile, key).present? }
+  end
+end

data/config/importmap.rb

@@ -0,0 +1 @@
+pin "controllers/turnstile_controller", to: "verify_human/turnstile_controller.js", preload: false

data/lib/verify_human/engine.rb

@@ -0,0 +1,21 @@
+module VerifyHuman
+  # Non-isolated engine: app/controllers/concerns and app/helpers merge into
+  # the host app's autoload and helper paths, so apps keep writing
+  # `include HumanVerification` and calling `human_verification_tag` with no
+  # namespace changes.
+  class Engine < ::Rails::Engine
+    initializer "verify_human.assets" do |app|
+      if app.config.respond_to?(:assets)
+        app.config.assets.paths << root.join("app/assets/javascripts")
+        # Sprockets needs an explicit precompile entry; Propshaft ignores this.
+        app.config.assets.precompile += %w[verify_human/turnstile_controller.js] if app.config.assets.respond_to?(:precompile)
+      end
+    end
+
+    # Pinned under controllers/ so stimulus-loading's lazyLoadControllersFrom
+    # discovers and registers the controller exactly like an app-local one.
+    initializer "verify_human.importmap", before: "importmap" do |app|
+      app.config.importmap.paths << root.join("config/importmap.rb") if defined?(Importmap)
+    end
+  end
+end

data/lib/verify_human/test_helpers.rb

@@ -0,0 +1,44 @@
+# Test support for apps using verify_human. Requires WebMock.
+#
+#   require "verify_human/test_helpers"
+#   include HumanVerification::TestHelpers
+module HumanVerification
+  module TestHelpers
+    # Swaps in credentials that answer turnstile keys while delegating every
+    # other lookup to the real credentials.
+    def with_human_verification_configured(&block)
+      credentials = Class.new(SimpleDelegator) do
+        def dig(*keys)
+          case keys
+          in [:turnstile, :secret_key] then "test-secret"
+          in [:turnstile, :site_key] then "test-site-key"
+          in [:turnstile, :invisible_secret_key] then "test-invisible-secret"
+          in [:turnstile, :invisible_site_key] then "test-invisible-site-key"
+          else super
+          end
+        end
+
+        # EncryptedConfiguration claims to respond to everything, which makes
+        # Minitest's stub treat this object as a callable and replace it with
+        # the result of #call. Deny :call so stub returns the object itself.
+        def respond_to?(name, include_private = false)
+          return false if name == :call
+          super
+        end
+      end.new(Rails.application.credentials)
+
+      Rails.application.stub(:credentials, credentials, &block)
+    end
+
+    def stub_human_verification(success:, action: nil)
+      body = {success: success}
+      body[:action] = action if action
+      stub_request(:post, HumanVerification::VERIFY_URL)
+        .to_return(body: body.to_json, headers: {"Content-Type" => "application/json"})
+    end
+
+    def stub_human_verification_outage
+      stub_request(:post, HumanVerification::VERIFY_URL).to_timeout
+    end
+  end
+end

data/lib/verify_human/version.rb

@@ -0,0 +1,3 @@
+module VerifyHuman
+  VERSION = "0.1.5"
+end

data/lib/verify_human.rb

@@ -0,0 +1,5 @@
+require "verify_human/version"
+require "verify_human/engine"
+
+module VerifyHuman
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: verify_human
+version: !ruby/object:Gem::Version
+  version: 0.1.5
+platform: ruby
+authors:
+- Marc Köhlbrugge
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: verify_human class macro, human_verification_tag view helper, and a Turbo-safe
+  Stimulus controller. Interaction-only Managed widgets by default, optional invisible-mode
+  widgets, fail-open verification with tight timeouts, per-form action enforcement.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- app/assets/javascripts/verify_human/turnstile_controller.js
+- app/controllers/concerns/human_verification.rb
+- app/helpers/human_verification_helper.rb
+- config/importmap.rb
+- lib/verify_human.rb
+- lib/verify_human/engine.rb
+- lib/verify_human/test_helpers.rb
+- lib/verify_human/version.rb
+homepage: https://github.com/marckohlbrugge/verify_human
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/marckohlbrugge/verify_human
+  bug_tracker_uri: https://github.com/marckohlbrugge/verify_human/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Human verification for Rails forms; Cloudflare Turnstile under the hood
+test_files: []