WIP: feat(captcha): implement captcha validation hooks and integrate into registration process

Author: rsmithlal

app/controllers/better_together/users/registrations_controller.rb

@@ -80,6 +80,13 @@ def create
           return
         end
 
+        # Validate captcha if enabled by host application
+        unless validate_captcha_if_enabled
+          build_resource(sign_up_params)
+          handle_captcha_validation_failure(resource)
+          return
+        end
+
         ActiveRecord::Base.transaction do
           super do |user|
             handle_user_creation(user) if user.persisted?
@@ -104,6 +111,25 @@ def set_required_agreements
         @code_of_conduct_agreement = BetterTogether::Agreement.find_by(identifier: 'code_of_conduct')
       end
 
+      # Hook method for host applications to implement captcha validation
+      # Override this method in host applications to add Turnstile or other captcha validation
+      # @return [Boolean] true if captcha is valid or not enabled, false if validation fails
+      def validate_captcha_if_enabled
+        # Default implementation - no captcha validation
+        # Host applications should override this method to implement their captcha logic
+        true
+      end
+
+      # Hook method for host applications to handle captcha validation failures
+      # Override this method in host applications to customize error handling
+      # @param resource [User] the user resource being created
+      def handle_captcha_validation_failure(resource)
+        # Default implementation - adds a generic error message
+        resource.errors.add(:base, I18n.t('better_together.registrations.captcha_validation_failed',
+                                          default: 'Security verification failed. Please try again.'))
+        respond_with resource
+      end
+
       def after_sign_up_path_for(resource)
         # Redirect to event if signed up via event invitation
         return better_together.event_path(@event_invitation.event) if @event_invitation&.event

app/views/devise/registrations/_extra_registration_fields.html.erb

@@ -0,0 +1,3 @@
+<%# Override this partial in your host app to add additional fields to the registration form %>
+<%# Place custom form elements here (e.g., CAPTCHA, extra validation fields, etc.) %>
+<%# Available locals: form (form builder), resource (user resource being created) %>

app/views/devise/registrations/new.html.erb

@@ -130,6 +130,9 @@
         <% end %>
       <% end %>
 
+      <!-- Host App Extensible Content (e.g., CAPTCHA, additional fields) -->
+      <%= render partial: 'devise/registrations/extra_registration_fields', locals: { form: f, resource: resource } %>
+
       <!-- Submit Button -->
       <div class="text-center">
         <%= f.submit t('.sign_up'), class: 'btn btn-primary' %>

config/locales/en.yml

@@ -1721,6 +1721,7 @@ en:
         agreements_must_accept: You must accept the Terms of Service and Privacy Policy
           to continue.
         agreements_required: You must accept the Privacy Policy and Terms of Service
+        captcha_validation_failed: Security verification failed. Please complete the security check and try again.
         code_of_conduct:
           label: I agree to the Code of Conduct
         email:

config/locales/es.yml

@@ -1737,6 +1737,7 @@ es:
         agreements_must_accept: You must accept the Terms of Service and Privacy Policy
           to continue.
         agreements_required: You must accept the Privacy Policy and Terms of Service
+        captcha_validation_failed: La verificación de seguridad falló. Por favor, completa la verificación de seguridad e inténtalo de nuevo.
         code_of_conduct:
           label: I agree to the Code of Conduct
         email:

config/locales/fr.yml

@@ -1745,6 +1745,7 @@ fr:
         agreements_must_accept: You must accept the Terms of Service and Privacy Policy
           to continue.
         agreements_required: You must accept the Privacy Policy and Terms of Service
+        captcha_validation_failed: La vérification de sécurité a échoué. Veuillez compléter la vérification de sécurité et réessayer.
         code_of_conduct:
           label: I agree to the Code of Conduct
         email:

spec/controllers/better_together/users/registrations_controller_hook_spec.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'rails_helper'
+
+RSpec.describe BetterTogether::Users::RegistrationsController, :skip_host_setup,
+               type: :controller do
+  include BetterTogether::CapybaraFeatureHelpers
+
+  routes { BetterTogether::Engine.routes }
+
+  before do
+    configure_host_platform
+  end
+
+  describe 'captcha hook methods', :no_auth do
+    describe '#validate_captcha_if_enabled' do
+      let(:controller_instance) { described_class.new }
+
+      it 'returns true by default (no captcha validation)' do
+        expect(controller_instance.send(:validate_captcha_if_enabled)).to be true
+      end
+    end
+
+    describe '#handle_captcha_validation_failure' do
+      let(:user) { build(:better_together_user) }
+      let(:controller_instance) { described_class.new }
+
+      before do
+        allow(controller_instance).to receive(:respond_with)
+      end
+
+      it 'adds error to resource and calls respond_with' do
+        controller_instance.send(:handle_captcha_validation_failure, user)
+
+        expect(user.errors[:base]).to include('Security verification failed. Please try again.')
+        expect(controller_instance).to have_received(:respond_with).with(user)
+      end
+    end
+  end
+
+  # Integration test for the complete captcha flow will be handled in feature specs
+end