spam_protect 0.0.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 642e4962310843445840e8799d51e75a6f02ee4eaa16b3f3be8298446fb9ed28
+  data.tar.gz: e2b35c61e0a5e20c270a327b2eb63ec1cc0505604ff7422307e8e25cc943b187
+SHA512:
+  metadata.gz: 40e5f2fc28e7761b82051430b5c66e09656ac93faf0fcb63925bcb43f26092226206d47e244606e091b3c453637b726bdebb0ca776fdf1c409e19fd43210b40a
+  data.tar.gz: 1f4feae42a54fd4e64dbe93e2320f4f6417172155beba6defc987493d34e7d414d1f6fb5b58153df9e47b03434bf5b6266af900d42dc2881af47bbfab04d64d7

data/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2025 Full Fat Software Ltd
+
+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 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,106 @@
+# spam_protect
+
+A lightweight Ruby gem to help reduce spam in Rails applications.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'spam_protect'
+```
+
+And then execute:
+
+    bundle install
+
+Then add the initializer to your Rails application:
+
+    bin/rails generate spam_protect:install
+
+## Usage
+
+Use the form helper method `spam_protect_field` within your forms to include the necessary spam protection fields:
+
+```ruby
+<%= form_for @comment do |f| >
+  <%= f.spam_protect_field %>
+<% end %>
+```
+
+This generates output similar to:
+
+```html
+<input type="text" name="comment[hp_field]" class="sp_hp" autocomplete="off" tabindex="-1" />
+<input type="hidden" name="comment[sp_timestamp]" value="encrypted_token_here" />
+```
+
+Visually hide the honeypot field with CSS:
+
+```css
+.sp_hp {
+  display: none !important;
+}
+```
+
+Include the JavaScript tag in any views where forms with spam protection are used:
+
+```ruby
+<%= spam_protect_javascript_tag %>
+```
+Check the results in your controller:
+
+```ruby
+class CommentsController < ApplicationController
+  def create
+    if validate_spam_protect_params(params[:comment])
+      @comment = Comment.new(comment_params)
+      ...
+    else
+      # handle spam case
+    end
+  end
+end
+```
+
+## Configuration
+
+You can customize the behavior of the gem by modifying the configuration file located at `config/initializers/spam_protect.rb`. Here you can set options such as encryption keys, token expiration times, and honeypot field names.
+
+```ruby
+# Example initializer for spam_protect
+SpamProtect.configure do |config|
+  # Custom field names (symbols)
+  config.honeypot_field = :hp_phone
+  config.timestamp_field = :hp_ts
+
+  # CSS class applied to the honeypot field
+  config.honeypot_class = "sp_hp"
+  config.wrapper_class = "spam_protect"
+
+  # Require JavaScript checks
+  config.require_js = true # Default is true
+
+  # Minimum seconds required between form render and submission
+  config.min_seconds = 3
+
+  # Secret key for signing/encrypting timestamps
+  config.signature_secret = SecureRandom.hex(64) # Will default to Rails secret_key_base if nil
+
+  # Expiry duration for the signature
+  config.signature_expiry = 6.hours
+end
+
+```
+
+## Development
+
+Clone the repository and run:
+
+    bundle install
+    bundle exec rspec
+    bundle exec rubocop # for linting
+
+### Requirements
+
+This gem requires Ruby 3.3 or newer. The repository `.ruby-version` is set to `3.4.1` but any Ruby >= 3.3 should work.

data/lib/generators/spam_protect/install/install_generator.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module SpamProtect
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates a SpamProtect initializer in config/initializers"
+
+      def copy_initializer
+        copy_file "spam_protect.rb", "config/initializers/spam_protect.rb"
+      end
+    end
+  end
+end

data/lib/generators/spam_protect/install/templates/spam_protect.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Example initializer for spam_protect
+SpamProtect.configure do |config|
+  # Custom field names (symbols)
+  # config.honeypot_field = :hp_phone
+  # config.timestamp_field = :hp_ts
+
+  # CSS class applied to the honeypot field
+  # config.honeypot_class = "sp_hp"
+  # config.wrapper_class = "spam_protect"
+
+  # Require JavaScript checks
+  # config.require_js = true # Default is true
+
+  # Minimum seconds required between form render and submission
+  # config.min_seconds = 3
+
+  # Secret key for signing/encrypting timestamps
+  # config.signature_secret = SecureRandom.hex(64) # Will default to Rails secret_key_base if nil
+
+  # Expiry duration for the signature
+  # config.signature_expiry = 6.hours
+end

data/lib/spam_protect/controller_helpers.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module SpamProtect
+  module ControllerHelpers
+    def validate_spam_protect_params(params, honeypot_key: nil, timestamp_key: nil, min_seconds: nil)
+      honeypot_key ||= SpamProtect.config.honeypot_field
+      timestamp_key ||= SpamProtect.config.timestamp_field
+      min_seconds ||= SpamProtect.config.min_seconds
+
+      unless params.is_a?(ActionController::Parameters)
+        raise ArgumentError, "params must be an instance of ActionController::Parameters"
+      end
+
+      unless params.key?(honeypot_key) && params.key?(timestamp_key)
+        raise ArgumentError, "params must include both #{honeypot_key} and #{timestamp_key} keys. Have you passed in params[:<model_name>]?"
+      end
+
+      honeypot_value = params[honeypot_key]
+      encrypted_timestamp = params[timestamp_key]
+
+      guardian = SpamProtect::Guardian.new(honeypot_value, encrypted_timestamp, cookies["spam_protect_token"], min_seconds)
+      guardian.valid?
+    end
+  end
+end

data/lib/spam_protect/current_time.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module SpamProtect
+  module CurrentTime
+    module_function
+
+    def now
+      Time.respond_to?(:current) ? Time.current : Time.now
+    end
+  end
+end

data/lib/spam_protect/encryption/payload.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module SpamProtect
+  module Encryption
+    class Payload
+      VALID_METHODS = %w[timestamp expires_at].freeze
+
+      def self.generate
+        new({
+          timestamp: CurrentTime.now.to_i,
+          expires_at: CurrentTime.now.to_i + SpamProtect.config.signature_expiry.to_i
+        })
+      end
+
+      def initialize(hash)
+        @hash = hash
+      end
+
+      def [](key)
+        if VALID_METHODS.include?(key.to_s)
+          send(key)
+        end
+      end
+
+      def to_h
+        {
+          "timestamp" => timestamp,
+          "expires_at" => expires_at
+        }
+      end
+
+      def expires_at
+        @hash[:expires_at] || @hash["expires_at"]
+      end
+
+      def timestamp
+        @hash[:timestamp] || @hash["timestamp"]
+      end
+
+      alias_method :expires_at?, :expires_at
+      alias_method :timestamp?, :timestamp
+    end
+  end
+end

data/lib/spam_protect/encryption/secret_key.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module SpamProtect
+  module Encryption
+    class SecretKey
+      class << self
+        def relevant_key!
+          result = from_configuration || from_rails
+
+          unless result.present?
+            raise Errors::NoSecretKey
+          end
+
+          unless defined?(ActiveSupport::KeyGenerator) && defined?(ActiveSupport::MessageEncryptor)
+            raise Errors::EncryptionUnavailable
+          end
+
+          key_len = ActiveSupport::MessageEncryptor.key_len
+
+          ActiveSupport::KeyGenerator.new(result).generate_key("spam_protect", key_len)
+        end
+
+        private
+
+        def from_configuration
+          SpamProtect.config.signature_secret
+        end
+
+        def from_rails
+          (defined?(Rails) && Rails.application.respond_to?(:secret_key_base)) ? Rails.application.secret_key_base : nil
+        end
+      end
+    end
+  end
+end

data/lib/spam_protect/encryption.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SpamProtect
+  module Encryption
+    module_function
+
+    # Encrypt and sign a payload (hash). Returns a token string or nil on failure.
+    def encrypt(payload)
+      encryptor = ActiveSupport::MessageEncryptor.new(secret_key)
+      encryptor.encrypt_and_sign(payload)
+    end
+
+    # Decrypt and verify a token. Returns the payload (usually a Hash) or nil.
+    def decrypt(token)
+      encryptor = ActiveSupport::MessageEncryptor.new(secret_key)
+      encryptor.decrypt_and_verify(token)
+    end
+
+    def secret_key
+      SecretKey.relevant_key!
+    end
+  end
+end

data/lib/spam_protect/errors/encryption_unavailable.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module SpamProtect
+  module Errors
+    class EncryptionUnavailable < Error
+      def message
+        "ActiveSupport encryption helpers are not available. Please ensure the 'activesupport' gem is included in your project."
+      end
+    end
+  end
+end

data/lib/spam_protect/errors/error.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module SpamProtect
+  module Errors
+    class Error < StandardError
+    end
+  end
+end

data/lib/spam_protect/errors/no_secret_key.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module SpamProtect
+  module Errors
+    class NoSecretKey < Error
+      def message
+        "No secret key available for signing/encryption. Please set `SpamProtect.config.signature_secret` or ensure Rails is loaded with a valid `secret_key_base`."
+      end
+    end
+  end
+end

data/lib/spam_protect/form_builder.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module SpamProtect
+  module FormBuilderMethods
+    def spam_protect_field(name: nil, timestamp_name: nil, wrapper: false)
+      name ||= SpamProtect.config.honeypot_field
+      timestamp_name ||= SpamProtect.config.timestamp_field
+      honeypot_class = SpamProtect.config.honeypot_class
+      wrapper_class = SpamProtect.config.wrapper_class
+
+      payload = Encryption::Payload.generate
+      token = Encryption.encrypt(payload.to_h)
+
+      honeypot = @template.text_field_tag("#{@object_name}[#{name}]", nil, class: honeypot_class, autocomplete: "off", tabindex: "-1")
+      signature_input = @template.hidden_field_tag("#{@object_name}[#{timestamp_name}]", token)
+
+      if wrapper
+        @template.content_tag(:div, honeypot + signature_input, class: wrapper_class)
+      else
+        (honeypot + signature_input).html_safe
+      end
+    end
+  end
+end

data/lib/spam_protect/guardian.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module SpamProtect
+  class Guardian
+    attr_reader :errors
+
+    def initialize(honeypot_value, encrypted_timestamp, cookie, min_seconds)
+      @honeypot_value = honeypot_value
+      @encrypted_timestamp = encrypted_timestamp
+      @cookie = cookie
+      @min_seconds = min_seconds
+      @errors = []
+    end
+
+    def valid?
+      payload = Encryption::Payload.new(
+        Encryption.decrypt(@encrypted_timestamp)
+      )
+
+      cookie_payload = if SpamProtect.config.require_js
+        Encryption::Payload.new(
+          Encryption.decrypt(@cookie)
+        )
+      end
+
+      payloads = [
+        payload,
+        cookie_payload
+      ].compact
+
+      honeypot_policy = Policies::HoneypotPolicy.new(@honeypot_value)
+      if honeypot_policy.invalid?
+        @errors.append "Honeypot field is filled in"
+        return false
+      end
+
+      cookie_policy = Policies::CookiePolicy.new(@cookie)
+      if cookie_policy.invalid?
+        @errors.append "Cookie is invalid"
+        return false
+      end
+
+      payloads.each do |p|
+        encryption_policy = Policies::EncryptionPolicy.new(p)
+        if encryption_policy.invalid?
+          @errors.append "Payload encryption is invalid or expired"
+          return false
+        end
+
+        timestamp_policy = Policies::TimestampPolicy.new(p["timestamp"], @min_seconds)
+        if timestamp_policy.invalid?
+          @errors.append "Form submitted too quickly"
+          return false
+        end
+      end
+
+      true
+    rescue
+      @errors.append "Encryption failure"
+      false
+    end
+  end
+end

data/lib/spam_protect/policies/base_policy.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module SpamProtect
+  module Policies
+    class BasePolicy
+      def valid?
+        raise NotImplementedError, "Subclasses must implement the valid? method"
+      end
+
+      def invalid?
+        !valid?
+      end
+    end
+  end
+end

data/lib/spam_protect/policies/cookie_policy.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module SpamProtect
+  module Policies
+    class CookiePolicy < BasePolicy
+      def initialize(cookie)
+        @cookie = cookie
+      end
+
+      def valid?
+        unless SpamProtect.config.require_js
+          return true
+        end
+
+        # Decryption/validity is checked elsewhere
+        @cookie.to_s.strip.present?
+      end
+    end
+  end
+end

data/lib/spam_protect/policies/encryption_policy.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module SpamProtect
+  module Policies
+    class EncryptionPolicy < BasePolicy
+      def initialize(payload)
+        @payload = payload
+      end
+
+      def valid?
+        correct_shape? && between_timestamps?
+      end
+
+      protected
+
+      def correct_shape?
+        @payload.timestamp? && @payload.expires_at?
+      end
+
+      def between_timestamps?
+        CurrentTime.now.between?(
+          Time.at(@payload["timestamp"].to_i),
+          Time.at(@payload["expires_at"].to_i)
+        )
+      end
+    end
+  end
+end

data/lib/spam_protect/policies/honeypot_policy.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module SpamProtect
+  module Policies
+    class HoneypotPolicy < BasePolicy
+      def initialize(value)
+        @value = value
+      end
+
+      def valid?
+        @value.nil? || @value.to_s.strip.empty?
+      end
+    end
+  end
+end

data/lib/spam_protect/policies/timestamp_policy.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module SpamProtect
+  module Policies
+    class TimestampPolicy < BasePolicy
+      def initialize(timestamp, min_seconds)
+        @timestamp = timestamp
+        @min_seconds = min_seconds
+      end
+
+      def valid?
+        return false if @timestamp.blank?
+
+        now = CurrentTime.now
+
+        submitted_at = Time.at(@timestamp.to_i)
+
+        (now - submitted_at) >= @min_seconds
+      end
+    end
+  end
+end

data/lib/spam_protect/railtie.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module SpamProtect
+  class Railtie < Rails::Railtie
+    initializer "spam_protect.action_view" do
+      ActiveSupport.on_load(:action_view) do
+        require_relative "form_builder"
+        require_relative "view_helpers"
+        ActionView::Helpers::FormBuilder.include(SpamProtect::FormBuilderMethods)
+        ActionView::Base.include(SpamProtect::ViewHelpers)
+      end
+    end
+
+    initializer "spam_protect.action_controller" do
+      ActiveSupport.on_load(:action_controller) do
+        require_relative "controller_helpers"
+        ActionController::Base.include(SpamProtect::ControllerHelpers) if defined?(ActionController::Base)
+      end
+    end
+  end
+end

data/lib/spam_protect/version.rb

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

data/lib/spam_protect/view_helpers.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module SpamProtect
+  module ViewHelpers
+    def spam_protect_javascript_tag
+      payload = Encryption::Payload.generate
+      token = Encryption.encrypt(payload.to_h)
+
+      js = <<~JS
+        (function(){
+          var token = #{token.to_json};
+          document.cookie = "spam_protect_token=" + encodeURIComponent(token) + "; path=/; SameSite=Lax; Secure";
+        })();
+      JS
+
+      %(<script>#{js}</script>).html_safe
+    end
+  end
+end

data/lib/spam_protect.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "action_view"
+require "active_support"
+require "active_support/core_ext/numeric/time"
+require "active_support/message_encryptor"
+require "active_support/key_generator"
+
+require_relative "spam_protect/errors/error"
+require_relative "spam_protect/errors/encryption_unavailable"
+require_relative "spam_protect/errors/no_secret_key"
+require_relative "spam_protect/encryption"
+require_relative "spam_protect/encryption/payload"
+require_relative "spam_protect/encryption/secret_key"
+require_relative "spam_protect/policies/base_policy"
+require_relative "spam_protect/policies/honeypot_policy"
+require_relative "spam_protect/policies/timestamp_policy"
+require_relative "spam_protect/policies/encryption_policy"
+require_relative "spam_protect/policies/cookie_policy"
+require_relative "spam_protect/guardian"
+require_relative "spam_protect/current_time"
+require_relative "spam_protect/form_builder"
+require_relative "spam_protect/view_helpers"
+require_relative "spam_protect/version"
+require_relative "spam_protect/railtie"
+require_relative "spam_protect/controller_helpers"
+
+module SpamProtect
+  # Configuration object for the gem
+  class Config
+    attr_accessor :honeypot_field, :timestamp_field, :honeypot_class,
+      :wrapper_class, :require_js, :min_seconds, :signature_secret,
+      :signature_expiry
+
+    def initialize
+      @honeypot_field = :hp_phone
+      @timestamp_field = :hp_ts
+      @honeypot_class = "sp_hp"
+      @wrapper_class = "spam_protect"
+      @require_js = true
+      @min_seconds = 2
+      @signature_secret = nil
+      @signature_expiry = 6.hours
+    end
+  end
+
+  def self.config
+    @config ||= Config.new
+  end
+
+  def self.configure
+    yield config if block_given?
+  end
+end

metadata

@@ -0,0 +1,134 @@
+--- !ruby/object:Gem::Specification
+name: spam_protect
+version: !ruby/object:Gem::Version
+  version: 0.0.4
+platform: ruby
+authors:
+- Full Fat Software
+bindir: bin
+cert_chain: []
+date: 2025-11-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  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: rubocop
+  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: standard
+  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: rubocop-performance
+  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.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+description: spam_protect stops contact message spam in rails applications by adding
+  honeypot fields and timestamp checks.
+email:
+- hey@fullfatsoftware.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/generators/spam_protect/install/install_generator.rb
+- lib/generators/spam_protect/install/templates/spam_protect.rb
+- lib/spam_protect.rb
+- lib/spam_protect/controller_helpers.rb
+- lib/spam_protect/current_time.rb
+- lib/spam_protect/encryption.rb
+- lib/spam_protect/encryption/payload.rb
+- lib/spam_protect/encryption/secret_key.rb
+- lib/spam_protect/errors/encryption_unavailable.rb
+- lib/spam_protect/errors/error.rb
+- lib/spam_protect/errors/no_secret_key.rb
+- lib/spam_protect/form_builder.rb
+- lib/spam_protect/guardian.rb
+- lib/spam_protect/policies/base_policy.rb
+- lib/spam_protect/policies/cookie_policy.rb
+- lib/spam_protect/policies/encryption_policy.rb
+- lib/spam_protect/policies/honeypot_policy.rb
+- lib/spam_protect/policies/timestamp_policy.rb
+- lib/spam_protect/railtie.rb
+- lib/spam_protect/version.rb
+- lib/spam_protect/view_helpers.rb
+homepage: https://github.com/fullfatsoftware/spam_protect
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: A lightweight Ruby gem to help reduce spam in rails applications
+test_files: []