honeypot_guard 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a7e5e0d2220ec88464f190b4a9e35b30bf671df65c60d58a95398d91c8028931
+  data.tar.gz: 07221aa198dedf7070a0471b0dd5ac5e17abd567d555b5ed6ccb7bd5126c15e8
+SHA512:
+  metadata.gz: f51cb80f9a0b0612f3ae1cad02cd791331eaab27658115dbc1903e34cad04dad1b24dd9a3cdc5ab3eccf63cbfb413b2eafefc38b633af1e442731542b8b330e0
+  data.tar.gz: 0b44b0aa13811e08f4458a07287b2123475a6840a23a7b76e2a8b39a9a42f5e4b801ba67819b7527de93e3acf12b9d416beb3fc64d9ddb28cda99f5b52a23a23

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release
+- Adds `spam_trap_fields` view helper
+- Adds `filter_spam` controller before_action

data/CONTRIBUTING.md

@@ -0,0 +1,56 @@
+# 🤝 Contributing
+
+Thanks for your interest in contributing to **HoneypotGuard** 🛡️
+
+---
+
+## 🧪 Use the gem locally
+
+To test the gem in a Rails project, add it via a local path.
+
+In your Rails app `Gemfile`:
+
+```ruby
+gem "honeypot_guard", path: "../honeypot_guard"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+You can now use the gem normally in your views and controllers.
+
+---
+
+## ✅ Run the tests
+
+Install dependencies:
+
+```bash
+bundle install
+```
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+### 🚆 Test against a specific Rails version
+
+```bash
+BUNDLE_GEMFILE=gemfiles/rails_7.2.gemfile bundle exec rspec
+BUNDLE_GEMFILE=gemfiles/rails_8.0.gemfile bundle exec rspec
+```
+
+---
+
+## 📦 Contributing guidelines
+
+- 🔍 Keep changes small and focused
+- 🧪 Add tests when changing behavior
+- ✅ Make sure all tests pass before opening a PR
+
+Thank you for contributing 🙂❤️

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 OpenCodeForge
+
+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,125 @@
+<h1 align="left">
+  🛡️ HoneypotGuard
+  <a href="https://github.com/OpenCodeForge/honeypot_guard/actions/workflows/ci.yml">
+    <img align="right"
+         src="https://github.com/OpenCodeForge/honeypot_guard/actions/workflows/ci.yml/badge.svg"
+         alt="CI">
+  </a>
+</h1>
+
+HoneypotGuard is a **minimal Rails gem** that protects web forms from basic spam using:
+
+- 🍯 an invisible **honeypot field**
+- ⏱️ a simple **minimum submission delay**
+
+It works **at the controller level** (no model validations) and immediately rejects spam requests with **`422 Unprocessable Entity`**.
+
+Perfect for ✉️ **contact forms**, 💬 feedback forms, and other **non-persisted submissions**.
+
+---
+
+## 📦 Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "honeypot_guard"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+---
+
+## 🚀 Usage
+
+### 1️⃣ Add spam trap fields to your form
+
+Inside any `form_with` or `form_for` block:
+
+```erb
+<%= form_with url: contact_messages_path do |f| %>
+  <%= spam_trap_fields %>
+
+  <%= f.text_field :name %>
+  <%= f.email_field :email %>
+  <%= f.text_area :message %>
+  <%= f.submit "Send" %>
+<% end %>
+```
+
+This injects automatically:
+- 🕳️ an invisible honeypot input
+- 🧭 a hidden timestamp input
+
+---
+
+### 2️⃣ Enable spam filtering in the controller
+
+Include the controller concern and add the `before_action`:
+
+```ruby
+class ContactMessagesController < ApplicationController
+  include HoneypotGuard::Controller
+
+  before_action :filter_spam, only: :create
+
+  def create
+    # normal processing
+    redirect_to root_path, notice: "Message sent"
+  end
+end
+```
+
+If spam is detected, the request is immediately stopped with:
+
+```http
+422 Unprocessable Entity
+```
+
+---
+
+## ⚙️ Configuration (Optional)
+
+Create an initializer:
+
+```ruby
+# config/initializers/honeypot_guard.rb
+HoneypotGuard.configure do |config|
+  config.min_delay = 3 # seconds
+  # config.honeypot_field = :website
+  # config.timestamp_field = :rendered_at
+end
+```
+
+---
+
+## 🧠 How It Works
+
+A request is considered spam if **any** of the following is true:
+
+1. 🚨 The honeypot field is filled
+2. ⚡ The form is submitted faster than the configured minimum delay
+
+✅ No JavaScript  
+✅ No model validation  
+✅ No database access
+
+---
+
+## ⚠️ Limitations
+
+HoneypotGuard is intentionally simple:
+
+- ❌ Not effective against advanced bots or direct HTTP submissions
+- ❌ Does not replace rate limiting or firewalls
+- ✅ Best used alongside tools like **Rack::Attack**
+
+---
+
+## 📄 License
+
+MIT License

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/gemfiles/rails_7.2.gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+gem "rails", "~> 7.2.0"
+
+gemspec path: ".."

data/gemfiles/rails_8.0.gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+gem "rails", "~> 8.0.0"
+
+gemspec path: ".."

data/gemfiles/rails_8.1.gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+gem "rails", "~> 8.1.0"
+
+gemspec path: ".."

data/lib/honeypot_guard/controller.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module HoneypotGuard
+  # Controller helpers used to filter out simple spam submissions.
+  #
+  # This module is intended to be included in Rails controllers
+  # handling form submissions, and works in combination with the
+  # +spam_trap_fields+ view helper.
+  #
+  module Controller
+    extend ActiveSupport::Concern
+
+    private
+
+    # Filters out obvious spam submissions based on:
+    #
+    # - a honeypot field that must remain empty
+    # - a minimum delay between form render and submission
+    #
+    # Typical usage in a controller:
+    #
+    #   class ContactMessagesController < ApplicationController
+    #     include HoneypotGuard::Controller
+    #
+    #     before_action :filter_spam, only: :create
+    #   end
+    #
+    # Combined with the ViewHelpers:
+    #
+    #   <%= form_with model: @contact_message do |f| %>
+    #     <%= spam_trap_fields %>
+    #     ...
+    #   <% end %>
+    #
+    # Behaviour:
+    # - reads the configured honeypot and timestamp fields from +params+
+    # - if spam is detected, logs a message and responds with <tt>422 Unprocessable Entity</tt>
+    # - the controller action is not executed in that case
+    #
+    def filter_spam
+      hp_name = HoneypotGuard.honeypot_field.to_s
+      ts_name = HoneypotGuard.timestamp_field.to_s
+
+      honeypot = params[hp_name]
+      timestamp = params[ts_name]
+
+      if spam_detected?(honeypot, timestamp)
+        Rails.logger.info "[HoneypotGuard] Blocked spam from #{request.remote_ip}"
+        head :unprocessable_entity
+      end
+    end
+
+    def spam_detected?(honeypot, timestamp)
+      # 1) Honeypot field must stay empty
+      return true if honeypot.present?
+
+      # 2) Check minimal delay
+      return false if timestamp.blank?
+
+      ts = Integer(timestamp) rescue nil
+      return false unless ts
+
+      delay = Time.now.to_i - ts
+      delay < HoneypotGuard.min_delay.to_i
+    end
+  end
+end

data/lib/honeypot_guard/railtie.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module HoneypotGuard
+  class Railtie < Rails::Railtie
+    initializer "honeypot_guard.view_helpers" do
+      ActiveSupport.on_load(:action_view) do
+        include HoneypotGuard::ViewHelpers
+      end
+    end
+  end
+end

data/lib/honeypot_guard/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HoneypotGuard
+  VERSION = "0.1.0"
+end

data/lib/honeypot_guard/view_helpers.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "action_view"
+require "uri"
+
+module HoneypotGuard
+  # View helpers used to inject spam trap fields into Rails forms.
+  #
+  # This module provides helpers meant to be used in form views
+  # and works in combination with the +filter_spam+ controller
+  # method.
+  #
+  module ViewHelpers
+    # Injects invisible spam trap fields into a form.
+    #
+    # This helper adds:
+    # - a honeypot field that should stay empty
+    # - a hidden timestamp used to detect fast submissions
+    #
+    # It must be used in combination with the
+    # +filter_spam+ controller method.
+    #
+    # View example:
+    #
+    #   <%= form_with url: contact_messages_path do |f| %>
+    #     <%= spam_trap_fields %>
+    #     ...
+    #   <% end %>
+    #
+    # Controller example:
+    #
+    #   class ContactMessagesController < ApplicationController
+    #     include HoneypotGuard::Controller
+    #     before_action :filter_spam, only: :create
+    #   end
+    #
+    def spam_trap_fields
+      hp = HoneypotGuard.honeypot_field
+      ts = HoneypotGuard.timestamp_field
+
+      honeypot_html = content_tag(
+        :div,
+        class: "hp-field",
+        style: "position:absolute; left:-9999px; top:-9999px;"
+      ) do
+        label_tag(hp, "Leave this field empty") +
+          text_field_tag(hp, nil, autocomplete: "off")
+      end
+
+      timestamp_html = hidden_field_tag(ts, Time.now.to_i)
+
+      honeypot_html + timestamp_html
+    end
+  end
+end

data/lib/honeypot_guard.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "honeypot_guard/version"
+require "honeypot_guard/controller"
+require "honeypot_guard/view_helpers"
+require "honeypot_guard/railtie" if defined?(Rails::Railtie)
+
+# Minimal spam protection for Rails forms.
+#
+# Public API:
+#
+# Controller:
+# - +filter_spam+: before_action to block obvious spam submissions
+#
+# Views:
+# - +spam_trap_fields+: injects honeypot and timestamp fields into forms
+#
+module HoneypotGuard
+  class << self
+    # Name of the honeypot field in params / forms
+    attr_accessor :honeypot_field
+
+    # Name of the timestamp field in params / forms
+    attr_accessor :timestamp_field
+
+    # Minimum delay (in seconds) between form rendering and submission
+    attr_accessor :min_delay
+  end
+
+  # Defaults
+  self.honeypot_field = :honeypot
+  self.timestamp_field = :form_rendered_at
+  self.min_delay = 3 # seconds
+
+  # Configures HoneypotGuard.
+  #
+  # This method allows you to customize the names of the
+  # honeypot and timestamp fields, as well as the minimum
+  # submission delay.
+  #
+  # Example:
+  #
+  #   # config/initializers/honeypot_guard.rb
+  #   HoneypotGuard.configure do |config|
+  #     config.min_delay = 3
+  #     # config.honeypot_field = :website
+  #     # config.timestamp_field = :rendered_at
+  #   end
+  #
+  def self.configure
+    yield self
+  end
+end

data/sig/honeypot_guard.rbs

@@ -0,0 +1,4 @@
+module HoneypotGuard
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: honeypot_guard
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- OpenCodeForge
+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.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+description: Minimal Rails gem that injects honeypot fields in forms and provides
+  a before_action returning 422 on spam.
+email:
+- contact@opencodeforge.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- gemfiles/rails_7.2.gemfile
+- gemfiles/rails_8.0.gemfile
+- gemfiles/rails_8.1.gemfile
+- lib/honeypot_guard.rb
+- lib/honeypot_guard/controller.rb
+- lib/honeypot_guard/railtie.rb
+- lib/honeypot_guard/version.rb
+- lib/honeypot_guard/view_helpers.rb
+- sig/honeypot_guard.rbs
+homepage: https://github.com/OpenCodeForge/honeypot_guard
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/OpenCodeForge/honeypot_guard
+  changelog_uri: https://github.com/OpenCodeForge/honeypot_guard/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Simple honeypot + delay spam guard for Rails controllers
+test_files: []