bot_challenge_page 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f388eccf957733cbaab0c019d82e9803b215bf8035b2b10dc7c656b821907e7d
+  data.tar.gz: 5b8126932d6bd901ddadab4dc68259bb1d2652992de882421fbfb0cfca67b500
+SHA512:
+  metadata.gz: e5a1b5e05aefd618aca8e14570e1e0c9a32f4d5144f6bd93dabae265d1ac69759ebe19bc4dcdaf9fc07a0b121ba81be819f4d46d7ac1b111454d1bb191131906
+  data.tar.gz: 58cf73819292626fc40a696fecb7c7737ab89f92b7093e9c707bb42fe95ff83cda7303c510b807ab41a221fd0fe5c0ed5d3251983b466726dea9f252f276bdac

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Jonathan Rochkind
+
+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,119 @@
+# BotChallengePage
+
+[![CI](https://github.com/samvera-labs/bot_challenge_page/actions/workflows/ci.yml/badge.svg)](https://github.com/samvera-labs/bot_challenge_page/actions/workflows/ci.yml)
+
+BotChallengePage lets you protect certain routes in your Rails app with [CloudFlare Turnstile](https://www.cloudflare.com/application-services/products/turnstile/) "CAPTHCA alternate" bot detector. Rather than the typical form submission use case for Turnstile, the user will be redirected to an interstitial challenge page, and redirected back on success.
+
+The motivating use case is fairly dumb (probably AI-related) crawlers, rather than targetted attacks, although we have tried to pay attention to security.  Many of our use cases were crawlers getting caught in "infinite" page variations by following every combination of voluminous facet values in search results in a near "infinite space", and causing us resource usage issues.
+
+![challenge page screenshot](docs/challenge-page-example.png)
+
+* You can optionally configure a rate limit that is allowed BEFORE the challenge is triggered
+  * Uses rack-attack to track rate, requires `Rails.cache` or `Rack::Attack.cache.store` to be set to a persistent shared high-performance cache, probably redis or memcached.
+
+* Once a challenge is passed, the pass is stored in a cookie, and a challenge won't be redisplayed for a configurable amount of time, so long as cookie is present
+
+* **Note:** User-agent does always need both cookies and javascript enabled to be able to pass challenge and get through!
+
+
+## Installation and Configuration
+
+* Get a CloudFlare account and Turnstile widget set up, which should give you a turnstile `sitekey` and `secret_key` you will need later in configuration.
+
+* `bundle add bot_challenge_page`, `bundle install`
+
+* Run the installer
+  * if you want to use rack-attack for some permissive pre-challenge rate, `rails g bot_challenge_page:install`
+  * If you do not want to use rack-attack and want challenge on FIRST request, `rails g bot_challenge_page:install --without-rack-attack`
+
+* Configure in the generated `./config/initializers/bot_challenge_page.rb`
+  * At a minimum you need to configure your Cloudflare Turnstile keys, and some paths to protect!
+    * Note that we can only protect GET paths, and also think about making sure you DON'T protect
+      any path your front-end needs JS `fetch` access to, as this would block it (at least
+      without custom front-end code we haven't really explored)
+    * If you are tempted to just protect `/` that may work, but worth thinking about any hearbeat paths, front-end requestable paths, or other machine-access-desired paths.
+  * Some other configuration options are offered -- more advanced/specialized ones are available that are not mentioned in generated config file, see [Config class](./app/models/bot_challenge_page/config.rb)
+
+
+## Customize challenge page display
+
+Some of the default challenge page html uses bootstrap alert classes. You may want to provide custom CSS if you aren't using bootstrap. You can see the default challenge page html at [challenge.html.erb](./app/views/bot_challenge_page/bot_challenge_page/challenge.html). You may wish to CSS-style other parts too!
+
+You can customize all text via I18n, see keys in [bot_challenge_page.en.yml](./config/locales/bot_challenge_page.en.yml)
+
+The challenge page by default will be displayed in your app's default rails `layout`.
+
+To customize the layout or challenge page HTML more further, you can use configuration to supply a `render` method for the controller pointing to your own templates or other layouts. You will probably want to re-use the partials we use in our default template, for standard functionality. And you'll want to provide `<template>` elements with the same id's for those elements, but can put whatever you want inside the templates!
+
+```ruby
+BotChallengePage::BotChallengePageController.bot_challenge_config.challenge_renderer = ()->  {
+  render "my_local_view_folder/whatever", layout "another_layout"
+  render layout: "another_layout" # default html but change layout. etc.
+}
+```
+
+## Example possible Blacklight config
+
+Many of us in my professional community use [blacklight](https://github.com/projectblacklight/blacklight).  Here's a possible sample blacklight config to:
+
+* Protect default catalog controller, including search results and any other actions
+* But give the user 3 free searches in a 36 hour period before challenged
+* For the #facet action used for "facet… more" links --  exempt from protection if the request is being made by a browser JS `fetch`, we just let those through. (Which means a determined attacker could do that on purpose, not defense against on purpose DDoS)
+
+```ruby
+Rails.application.config.to_prepare do
+  BotChallengePage::BotChallengePageController.bot_challenge_config.enabled = true
+
+  # Get from CloudFlare Turnstile: https://www.cloudflare.com/application-services/products/turnstile/
+  BotChallengePage::BotChallengePageController.bot_challenge_config.cf_turnstile_sitekey = "MUST GET"
+  BotChallengePage::BotChallengePageController.bot_challenge_config.cf_turnstile_secret_key = "MUST GET"
+
+  BotChallengePage::BotChallengePageController.bot_challenge_config.rate_limited_locations = [
+    "/catalog"
+  ]
+
+  # allow rate_limit_count requests in rate_limit_period, before issuing challenge
+  BotChallengePage::BotChallengePageController.bot_challenge_config.rate_limit_period = 36.hour
+  BotChallengePage::BotChallengePageController.bot_challenge_config.rate_limit_count = 3
+
+  BotChallengePage::BotChallengePageController.allow_exempt = ->(controller) {
+    # Excempt any Catalog #facet action that looks like an ajax/fetch request, the redirect
+    # ain't gonna work there, we just exempt it.
+    #
+    # sec-fetch-dest is set to 'empty' by browser on fetch requests, to limit us further;
+    # sure an attacker could fake it, we don't mind if someone determined can avoid
+    # rate-limiting on this one action
+    ( controller.params[:action] == "facet" &&
+      controller.request.headers["sec-fetch-dest"] == "empty" &&
+      controller.kind_of?(CatalogController)
+    )
+  }
+
+  BotChallengePage::BotChallengePageController.rack_attack_init
+end
+
+```
+
+## Possible future features?
+
+* allow regex in default location_matcher? Easy to do if you want it, just say so.
+
+* We could support swap-in Turnstile-alternatives, like [hCAPTHCA](https://www.hcaptcha.com/), [Google reCAPTCHA v3](https://developers.google.com/recaptcha/docs/v3), or even open source proof of work implementations like [ALTCHA](https://altcha.org/docs/get-started/), [pow-bot-deterrent](https://github.com/sequentialread/pow-bot-deterrent), or [Friendly Captcha](https://github.com/FriendlyCaptcha/friendly-captcha-sdk).  But the (free) cost/benefit of Turnstile are pretty good, so I don't myself have a lot of motivation to add this complexity.
+
+* Something to make it easier to switch the challenge on only based on signals that server/app is under some defined heavy load?
+
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## See also/Acknowledgements
+
+* [Joe Corral's blog post](https://lehigh-university-libraries.github.io/blog/turnstile.html) about using this approach at Lehigh University Libraries with an islandora/drupal app.
+
+* Joe's [similar plugin for drupal](https://drupal.org/project/turnstile_protect)
+
+* [Similar feature built into PHP VuFind app](https://github.com/vufind-org/vufind/pull/4079)
+
+* Wow only after I developed all this did I notice [rails-cloudflare-turnstile](https://github.com/instrumentl/rails-cloudflare-turnstile) which implements some pieces that could have been re-used here, but I feel good.
+
+* And yet another implementation in Rails that perhaps makes more assumptions about use cases, [turnstile-captcha](https://github.com/pfeiffer/turnstile-captcha). Haven't looked at it much.

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("spec/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'

data/app/controllers/bot_challenge_page/bot_challenge_page_controller.rb

@@ -0,0 +1,160 @@
+require 'http'
+
+# This controller has actions for issuing a challenge page for CloudFlare Turnstile product,
+# and then redirecting back to desired page.
+#
+# It also includes logic for configuring rack attack and a Rails controller filter to enforce
+# redirection to these actions. All the logic related to bot detection with turnstile is
+# mostly in this file -- with very flexible configuration in class_attributes -- to faciliate
+# future extraction to a re-usable gem if desired.
+#
+#
+module BotChallengePage
+  class BotChallengePageController < ::ApplicationController
+    # Config for bot detection is held in class object here -- idea is
+    # to support different controllers with different config protecting
+    # different paths in your app if you like, is why config is with controller
+    class_attribute :bot_challenge_config, default: ::BotChallengePage::Config.new
+
+    delegate :cf_turnstile_js_url, :cf_turnstile_sitekey, :still_around_delay_ms, to: :bot_challenge_config
+    helper_method :cf_turnstile_js_url, :cf_turnstile_sitekey, :still_around_delay_ms
+
+    SESSION_DATETIME_KEY = "t"
+    SESSION_IP_KEY = "i"
+
+    # for allowing unsubscribe for testing
+    class_attribute :_track_notification_subscription, instance_accessor: false
+
+    # perhaps in an initializer, and after changing any config, run:
+    #
+    #     Rails.application.config.to_prepare do
+    #       BotChallengePage::BotChallengePageController.rack_attack_init
+    #     end
+    #
+    # Safe to call more than once if you change config and want to call again, say in testing.
+    def self.rack_attack_init
+      self._rack_attack_uninit # make it safe for calling multiple times
+
+      ## Turnstile bot detection throttling
+      #
+      # for paths matched by `rate_limited_locations`, after over rate_limit count requests in rate_limit_period,
+      # token will be stored in rack env instructing challenge is required.
+      #
+      # For actual challenge, need before_action in controller.
+      #
+      # You could rate limit detect on wider paths than you actually challenge on, or the same. You probably
+      # don't want to rate-limit detect on narrower list of paths than you challenge on!
+      Rack::Attack.track("bot_detect/rate_exceeded/#{self.name}",
+          limit: self.bot_challenge_config.rate_limit_count,
+          period: self.bot_challenge_config.rate_limit_period) do |req|
+        if self.bot_challenge_config.enabled && self.bot_challenge_config.location_matcher.call(req, self.bot_challenge_config)
+          self.bot_challenge_config.rate_limit_discriminator.call(req, self.bot_challenge_config)
+        end
+      end
+
+      self._track_notification_subscription = ActiveSupport::Notifications.subscribe("track.rack_attack") do |_name, _start, _finish, request_id, payload|
+        rack_request = payload[:request]
+        rack_env     = rack_request.env
+        match_name = rack_env["rack.attack.matched"]  # name of rack-attack rule
+                                                      #
+        if match_name == "bot_detect/rate_exceeded/#{self.name}"
+          match_data   = rack_env["rack.attack.match_data"]
+          match_data_formatted = match_data.slice(:count, :limit, :period).map { |k, v| "#{k}=#{v}"}.join(" ")
+          discriminator = rack_env["rack.attack.match_discriminator"] # unique key for rate limit, usually includes ip
+
+          rack_env[self.bot_challenge_config.env_challenge_trigger_key] = true
+        end
+      end
+    end
+
+    def self._rack_attack_uninit
+      Rack::Attack.track("bot_detect/rate_exceeded/#{self.name}") {} # overwrite track name with empty proc
+      ActiveSupport::Notifications.unsubscribe(self._track_notification_subscription) if self._track_notification_subscription
+      self._track_notification_subscription = nil
+    end
+
+    # Usually in your ApplicationController,
+    #
+    #     before_action { |controller| BotChallengePage::BotChallengePageController.bot_challenge_enforce_filter(controller) }
+    #
+    # @param immediate [Boolean] always force bot protection, ignore any allowed pre-challenge rate limit
+    def self.bot_challenge_enforce_filter(controller, immediate: false)
+      if self.bot_challenge_config.enabled &&
+          (controller.request.env[self.bot_challenge_config.env_challenge_trigger_key] || immediate) &&
+          ! self._bot_detect_passed_good?(controller.request) &&
+          ! controller.kind_of?(self) && # don't ever guard ourself, that'd be a mess!
+          ! self.bot_challenge_config.allow_exempt.call(controller, self.bot_challenge_config)
+
+        # we can only do GET requests right now
+        if !controller.request.get?
+          Rails.logger.warn("#{self}: Asked to protect request we could not, unprotected: #{controller.request.method} #{controller.request.url}, (#{controller.request.remote_ip}, #{controller.request.user_agent})")
+          return
+        end
+
+        Rails.logger.info("#{self.name}: Cloudflare Turnstile challenge redirect: (#{controller.request.remote_ip}, #{controller.request.user_agent}): from #{controller.request.url}")
+        # status code temporary
+        controller.redirect_to controller.bot_detect_challenge_path(dest: controller.request.original_fullpath), status: 307
+      end
+    end
+
+    # Does the session already contain a bot detect pass that is good for this request
+    # Tie to IP address to prevent session replay shared among IPs
+    def self._bot_detect_passed_good?(request)
+      session_data = request.session[self.bot_challenge_config.session_passed_key]
+
+      return false unless session_data && session_data.kind_of?(Hash)
+
+      datetime = session_data[SESSION_DATETIME_KEY]
+      ip   = session_data[SESSION_IP_KEY]
+
+      (ip == request.remote_ip) && (Time.now - Time.iso8601(datetime) < self.bot_challenge_config.session_passed_good_for )
+    end
+
+
+    def challenge
+      # possible custom render to choose layouts or templates, but normally
+      # we just do default rails render and this proc is empty.
+      if self.bot_challenge_config.challenge_renderer
+        instance_exec &self.bot_challenge_config.challenge_renderer
+      end
+    end
+
+    def verify_challenge
+      body = {
+        secret: self.bot_challenge_config.cf_turnstile_secret_key,
+        response: params["cf_turnstile_response"],
+        remoteip: request.remote_ip
+      }
+
+      http = HTTP.timeout(self.bot_challenge_config.cf_timeout)
+      response = http.post(self.bot_challenge_config.cf_turnstile_validation_url,
+        json: body)
+
+      result = response.parse
+      # {"success"=>true, "error-codes"=>[], "challenge_ts"=>"2025-01-06T17:44:28.544Z", "hostname"=>"example.com", "metadata"=>{"result_with_testing_key"=>true}}
+      # {"success"=>false, "error-codes"=>["invalid-input-response"], "messages"=>[], "metadata"=>{"result_with_testing_key"=>true}}
+
+      if result["success"]
+        # mark it as succesful in session, and record time. They do need a session/cookies
+        # to get through the challenge.
+        Rails.logger.info("#{self.class.name}: Cloudflare Turnstile validation passed api (#{request.remote_ip}, #{request.user_agent}): #{params["dest"]}")
+        session[self.bot_challenge_config.session_passed_key] = {
+          SESSION_DATETIME_KEY => Time.now.utc.iso8601,
+          SESSION_IP_KEY   => request.remote_ip
+        }
+      else
+        Rails.logger.warn("#{self.class.name}: Cloudflare Turnstile validation failed (#{request.remote_ip}, #{request.user_agent}): #{result}: #{params["dest"]}")
+      end
+
+      # let's just return the whole thing to client? Is there anything confidential there?
+      render json: result
+    rescue HTTP::Error, JSON::ParserError => e
+      # probably an http timeout? or something weird.
+      Rails.logger.warn("#{self.class.name}: Cloudflare turnstile validation error (#{request.remote_ip}, #{request.user_agent}): #{e}: #{response&.body}")
+      render json: {
+        success: false,
+        http_exception: e
+      }
+    end
+  end
+end

data/app/models/bot_challenge_page/config.rb

@@ -0,0 +1,116 @@
+module BotChallengePage
+  class Config
+    # meh let's do a little accessor definition to make this value class more legible
+
+    # default can be a proc, in which case it really is a proc as a value for default,
+    # the value is the proc!
+    def self.attribute(name, default:nil)
+      attr_defaults[name] = default
+      self.attr_accessor name
+    end
+
+    class_attribute :attr_defaults, default: {}, instance_accessor: false
+
+    def initialize(**values)
+      self.class.attr_defaults.merge(values).each_pair do |key, value|
+        # super hacky way to execute any procs in the context of this config,
+        # so they can access other config values easily.
+        if value.kind_of?(Proc)
+          newval = lambda do |*args|
+            self.instance_exec(*args, &value)
+          end
+        else
+          newval = value
+        end
+
+        send("#{key}=", newval)
+      end
+    end
+
+    attribute :enabled, default: false # Must set to true to turn on at all
+
+    attribute :cf_turnstile_sitekey, default: "1x00000000000000000000AA" # a testing key that always passes
+    attribute :cf_turnstile_secret_key, default: "1x0000000000000000000000000000000AA" # a testing key always passes
+    # Turnstile testing keys: https://developers.cloudflare.com/turnstile/troubleshooting/testing/
+
+    # up to rate_limit_count requests in rate_limit_period before challenged
+    attribute :rate_limit_period,  default: 12.hour
+    attribute :rate_limit_count,  default: 10
+
+    # how long is a challenge pass good for before re-challenge?
+    attribute :session_passed_good_for,  default: 24.hours
+
+    # An array, can be:
+    #   * a string, path prefix
+    #   * a hash of rails route-decoded params, like `{ controller: "something" }`,
+    #     or `{ controller: "something", action: "index" }
+    #     The hash is more expensive to check and uses some not-technically-public
+    #     Rails api, but it's just so convenient.
+    #
+    # Used by default :location_matcher, if set custom may not be used
+    attribute :rate_limited_locations, default: []
+
+    # Executed at the _controller_ filter level, to last minute exempt certain
+    # actions from protection.
+    attribute :allow_exempt, default: ->(controller, config) { false }
+
+    # replace with say `->() { render layout: 'something' }`, or `render "somedir/some_template"`
+    attribute :challenge_renderer, default: nil
+
+
+    # rate limit per subnet, following lehigh's lead, although we use a smaller
+    # subnet: /24 for IPv4, and /72 for IPv6
+    # https://git.drupalcode.org/project/turnstile_protect/-/blob/0dae9f95d48f9d8cae5a8e61e767c69f64490983/src/EventSubscriber/Challenge.php#L140-151
+    attribute :rate_limit_discriminator, default: (lambda do |req, config|
+      if req.ip.index(":") # ipv6
+        IPAddr.new("#{req.ip}/24").to_string
+      else
+        IPAddr.new("#{req.ip}/72").to_string
+      end
+    rescue IPAddr::InvalidAddressError
+      req.ip
+    end)
+
+    attribute :location_matcher, default: ->(rack_req, config) {
+      parsed_route = nil
+      config.rate_limited_locations.any? do |val|
+        case val
+        when Hash
+          begin
+            # #recognize_path may e not techinically public API, and may be expensive, but
+            # no other way to do this, and it's mentioned in rack-attack:
+            # https://github.com/rack/rack-attack/blob/86650c4f7ea1af24fe4a89d3040e1309ee8a88bc/docs/advanced_configuration.md#match-actions-in-rails
+            # We do it lazily only if needed so if you don't want that don't use it.
+            parsed_route ||= rack_req.env["action_dispatch.routes"].recognize_path(rack_req.url, method: rack_req.request_method)
+            parsed_route && parsed_route >= val
+          rescue ActionController::RoutingError
+            false
+          end
+        when String
+          # string complete path at beginning, must end in ?, or end of string
+          /\A#{Regexp.escape val}(\/|\?|\Z)/ =~ rack_req.path
+        end
+      end
+    }
+    attribute :cf_turnstile_js_url, default: "https://challenges.cloudflare.com/turnstile/v0/api.js"
+    attribute :cf_turnstile_validation_url, default:  "https://challenges.cloudflare.com/turnstile/v0/siteverify"
+    attribute :cf_timeout, default: 3 # max timeout seconds waiting on Cloudfront Turnstile api
+
+
+    # key stored in Rails session object with channge passed confirmed
+    attribute :session_passed_key, default: "bot_detection-passed"
+
+    # key in rack env that says challenge is required
+    attribute :env_challenge_trigger_key, default: "bot_detect.should_challenge"
+
+    attribute :still_around_delay_ms, default: 1200
+
+    # make sure dup dups all attributes please
+    def initialize_dup(source)
+      self.class.attr_defaults.keys.each do |attr_key|
+        instance_variable_set("@#{attr_key}", instance_variable_get("@#{attr_key}").deep_dup)
+        super
+      end
+    end
+  end
+end

data/app/views/bot_challenge_page/_local_turnstile_script_tag.html.erb

@@ -0,0 +1,72 @@
+<%# we deliver our simple javascript as inline script to make deployment more
+  reliable without having to deal with different asset pipelines, and it's really a fine choice anyway  %>
+
+<script type="text/javascript">
+  async function turnstileCallback(token) {
+    try {
+      // I don't know if we could be disabling CSRF instead for this one, but we'll just use it
+      const csrfToken = document.querySelector("[name='csrf-token']");
+
+      const response = await fetch('<%= bot_detect_challenge_path %>', {
+        method: 'POST',
+        headers: {
+          "X-CSRF-Token": csrfToken?.content,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ cf_turnstile_response: token }),
+      });
+
+      if (!response.ok) {
+        throw new Error('bad response: ' + response.status + ": " + response.url);
+      }
+
+      // This page may end up staying around on sucesss, stay if the dest url is a media
+      // type that can only be downloaded.
+      //
+      // When so, if the page stays around, it may end up
+      // calling turnstile and this callback over and over again, without an  (that
+      // we're not tracking) this will remove the most recent turnstile widget executed,
+      // we only expect one.
+      turnstile.remove();
+
+      result = await response.json();
+      if (result["success"] == true) {
+        const dest = new URLSearchParams(window.location.search).get("dest");
+        // For security make sure it only has path and on
+        if (!dest.startsWith("/") || dest.startsWith("//")) {
+          throw new Error("illegal non-local redirect: " + dest);
+        }
+
+        // in case this page stays around, (say it was rediret to media asset), let's add a failsafe message after
+        // a couple seconds.
+        const delay = document.querySelector("#botChallengePageStillAroundTemplate")?.getAttribute("data-still-around-delay-ms") || 1200;
+        window.setTimeout(function() {
+          _displayStillAroundNote()
+        }, delay);
+
+        // replace the challenge page in history
+        window.location.replace(dest);
+      } else {
+        console.error("Turnstile response reported as failure: " + JSON.stringify(result))
+        _displayChallengeError();
+      }
+    } catch(error) {
+      console.error("Error processing turnstile challenge backend action: " + error);
+      _displayChallengeError();
+    }
+  }
+
+  function _displayChallengeError() {
+    const template = document.querySelector("#botChallengePageErrorTemplate");
+    const clone = template.content.cloneNode(true);
+    document.querySelector(".cf-turnstile").replaceChildren(clone);
+  }
+
+  // If the page is still around after location changed, what's up?
+  // Warn them they might need t use back button, maybe it was a media download
+  function _displayStillAroundNote() {
+    const template = document.querySelector("#botChallengePageStillAroundTemplate");
+    const clone = template.content.cloneNode(true);
+    document.querySelector(".cf-turnstile")?.after(clone);
+  }
+</script>

data/app/views/bot_challenge_page/_turnstile_widget_placeholder.html.erb

@@ -0,0 +1,5 @@
+<div
+  class="cf-turnstile"
+  data-sitekey="<%= cf_turnstile_sitekey %>"
+  data-callback="turnstileCallback"
+></div>

data/app/views/bot_challenge_page/bot_challenge_page/challenge.html.erb

@@ -0,0 +1,29 @@
+<div class="bot_challenge_page">
+  <h1 class="mb-4"><%= t('bot_challenge_page.title') %></h1>
+
+  <%= render "bot_challenge_page/turnstile_widget_placeholder" %>
+
+  <noscript>
+    <div class="alert alert-danger"><%= t('bot_challenge_page.noscript') %></div>
+  </noscript>
+
+  <%= t('bot_challenge_page.blurb_html') %>
+
+  <template id="botChallengePageErrorTemplate">
+    <div class="alert alert-danger" role="alert">
+      <i class="fa fa-exclamation-triangle" aria-hidden="true"></i>
+      <%= t('bot_challenge_page.error') %>
+    </div>
+  </template>
+
+  <template id="botChallengePageStillAroundTemplate" data-still_around_delay_ms="<%= still_around_delay_ms %>">
+    <div class="alert alert-info" role="alert">
+      <i class="fa fa-info-circle" aria-hidden="true"></i>
+      <%= t('bot_challenge_page.still_around') %>
+    </div>
+  </template>
+
+  <script src="<%= cf_turnstile_js_url %>" async defer></script>
+
+  <%= render "bot_challenge_page/local_turnstile_script_tag" %>
+</div>

data/config/locales/bot_challenge_page.en.yml

@@ -0,0 +1,7 @@
+en:
+  bot_challenge_page:
+    title: Traffic control and bot detection...
+    noscript: Sorry, Javascript is required to be enabled for our traffic check, and does not appear available.
+    blurb_html: <p>If this check is preventing you from making use of our resources, make sure you have cookies enabled.</p>
+    error: Check failed. Sorry, something has gone wrong, or your traffic looks unusual to us. You can try refreshing this page to try again.
+    still_around: The traffic check has completed. You may need to return to your original browser tab or press the back button.

data/config/routes.rb

@@ -0,0 +1,2 @@
+Rails.application.routes.draw do
+end

data/lib/bot_challenge_page/engine.rb

@@ -0,0 +1,4 @@
+module BotChallengePage
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/bot_challenge_page/version.rb

@@ -0,0 +1,3 @@
+module BotChallengePage
+  VERSION = "0.1.0"
+end

data/lib/bot_challenge_page.rb

@@ -0,0 +1,6 @@
+require "bot_challenge_page/version"
+require "bot_challenge_page/engine"
+
+module BotChallengePage
+  # Your code goes here...
+end

data/lib/generators/bot_challenge_page/install_generator.rb

@@ -0,0 +1,45 @@
+module BotChallengePage
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path("templates", __dir__)
+
+    class_option :'rack_attack', type: :boolean, default: true, desc: "Support rate-limit allowance configuration"
+
+    def generate_routes
+      route 'get "/challenge", to: "bot_challenge_page/bot_challenge_page#challenge", as: :bot_detect_challenge'
+      route 'post "/challenge", to: "bot_challenge_page/bot_challenge_page#verify_challenge"'
+    end
+
+    def add_before_filter_enforcement
+      inject_into_class "app/controllers/application_controller.rb", "ApplicationController" do
+        filter_code = if options[:rack_attack]
+          "BotChallengePage::BotChallengePageController.bot_challenge_enforce_filter(controller)"
+        else
+          "BotChallengePage::BotChallengePageController.bot_challenge_enforce_filter(controller, immediate: true)"
+        end
+
+        <<-EOS
+  # This will only protect CONFIGURED routes, but also could be put on just certain
+  # controllers, it does not need to be in ApplicationController
+  before_action do |controller|
+    #{filter_code}
+  end
+
+        EOS
+      end
+    end
+
+    def add_rack_attack_require_if_needed
+      if options[:rack_attack]
+        # since it's an intermediate dependency, we need to require it after rails
+        # so it will load it's rails stuff
+        inject_into_file "config/application.rb", "\nrequire 'rack/attack'\n", after: /require.*rails\/[^\n]+\n/m
+
+      end
+    end
+
+    def copy_initializer_file
+      template "initializer.rb.erb", "config/initializers/bot_challenge_page.rb"
+    end
+
+  end
+end

data/lib/generators/bot_challenge_page/templates/initializer.rb.erb

@@ -0,0 +1,50 @@
+Rails.application.config.to_prepare do
+
+  BotChallengePage::BotChallengePageController.bot_challenge_config.enabled = true
+
+  # Get from CloudFlare Turnstile: https://www.cloudflare.com/application-services/products/turnstile/
+  BotChallengePage::BotChallengePageController.bot_challenge_config.cf_turnstile_sitekey = "MUST GET"
+  BotChallengePage::BotChallengePageController.bot_challenge_config.cf_turnstile_secret_key = "MUST GET"
+
+  # What paths do you want to protect?
+  #
+  # You can use path prefixes: "/catalog" or even "/"
+  #
+  # Or hashes with controller and/or action:
+  #
+  #   { controller: "catalog" }
+  #   { controller: "catalog", action: "index" }
+  #
+  # Note that we can only protect GET paths, and also think about making sure you DON'T protect
+  # any path your front-end needs JS `fetch` access to, as this would block it (at least
+  # without custom front-end code we haven't really explored)
+
+  BotChallengePage::BotChallengePageController.bot_challenge_config.rate_limited_locations = [
+  ]
+
+  # How long will a challenge success exempt a session from further challenges?
+  # BotChallengePage::BotChallengePageController.bot_challenge_config.session_passed_good_for = 36.hours
+
+  <%- if options[:rack_attack] %>
+  # allow rate_limit_count requests in rate_limit_period, before issuing challenge
+  BotChallengePage::BotChallengePageController.bot_challenge_config.rate_limit_period = 12.hour
+  BotChallengePage::BotChallengePageController.bot_challenge_config.rate_limit_count = 2
+  <% end -%>
+
+  # Exempt some requests from bot challenge protection
+  # BotChallengePage::BotChallengePageController.allow_exempt = ->(controller) {
+  #   # controller.params
+  #   # controller.request
+  #   # controller.session
+
+  #   # Here's a way to identify browser `fetch` API requests; note
+  #   # it can be faked by an "attacker"
+  #   controller.request.headers["sec-fetch-dest"] == "empty"
+  # }
+
+  # More configuration is available
+
+  <%- if options[:rack_attack] %>
+  BotChallengePage::BotChallengePageController.rack_attack_init
+  <% end %>
+end

data/lib/tasks/bot_challenge_page_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :bot_challenge_page do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,193 @@
+--- !ruby/object:Gem::Specification
+name: bot_challenge_page
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jonathan Rochkind
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-02-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: capybara
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.40'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.40'
+- !ruby/object:Gem::Dependency
+  name: selenium-webdriver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.5'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.1'
+- !ruby/object:Gem::Dependency
+  name: rack-attack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.7'
+- !ruby/object:Gem::Dependency
+  name: http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+description:
+email:
+- jonathan@dnil.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/bot_challenge_page/bot_challenge_page_controller.rb
+- app/models/bot_challenge_page/config.rb
+- app/views/bot_challenge_page/_local_turnstile_script_tag.html.erb
+- app/views/bot_challenge_page/_turnstile_widget_placeholder.html.erb
+- app/views/bot_challenge_page/bot_challenge_page/challenge.html.erb
+- config/locales/bot_challenge_page.en.yml
+- config/routes.rb
+- lib/bot_challenge_page.rb
+- lib/bot_challenge_page/engine.rb
+- lib/bot_challenge_page/version.rb
+- lib/generators/bot_challenge_page/install_generator.rb
+- lib/generators/bot_challenge_page/templates/initializer.rb.erb
+- lib/tasks/bot_challenge_page_tasks.rake
+homepage: https://github.com/samvera-labs/bot_challenge_page
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/samvera-labs/bot_challenge_page
+  source_code_uri: https://github.com/samvera-labs/bot_challenge_page
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.9
+signing_key:
+specification_version: 4
+summary: Show a bot challenge interstitial for Rails, usually using Cloudflare Turnstile
+test_files: []