spam_protect 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d05346c0bc0002289dedf2bd5504281d1d9d401242129a27deb589ee1b4405a6
-  data.tar.gz: 9a9cf534be87919e93345fc1506da429a20363633330187041ec232e7aae2a85
+  metadata.gz: d101c1fa1655923be2915a246c7d892fe8e91bd3abd7b3e97530e23a4a6d427f
+  data.tar.gz: a683fea849f5b8c439fbbedb23a781df713ab01c4e4baf6797e5a997b69b4989
 SHA512:
-  metadata.gz: f1ce0755b323d86762125f0e335fcab9b6461321b600da365f5c4a90a7101425a4f290e856d52e8e7cbbdda6d74393983727685802f17d6bea0ef29fd8b46657
-  data.tar.gz: 1897fc01e73d241daa5da29040453a3571c8fd33929e145d3422429288f9b3d1af5c05494d6542b48c116896a2c80fb0f4317236ee9377ca3ae03bde25adcd22
+  metadata.gz: 07a3893f6100fc8f28c6adf2976539fce30be6b8fb96a6285156c5bf351b79a8e7c9ecbd1798431483bc0a1411ce8b5c8944e136bcbef96acc51c06f9a9e8593
+  data.tar.gz: 3ea0a101bb740b8d076e2b5c60201adc495bed51665d35d3afd2a42f72d0f79901885ad3f6ad8ff9541ebf4c8c6b3416c06e04cf466c0393e67a80db97fcc61a

data/README.md

@@ -1,6 +1,6 @@
 # spam_protect
 
-A lightweight Ruby gem to help reduce spam in Rails applications.
+A lightweight Ruby gem to help reduce spam in Rails applications without relying on CAPTCHAs or third-party services. It uses a combination of honeypot fields, timestamp tokens, and optional JavaScript checks to identify and block automated spam submissions.
 
 ## Installation
 
@@ -11,12 +11,14 @@ gem 'spam_protect'
 ```
 
 And then execute:
-
-    bundle install
+```bash
+bundle install
+```
 
 Then add the initializer to your Rails application:
-
-    bin/rails generate spam_protect:install
+```bash
+ bin/rails generate spam_protect:install
+```
 
 ## Usage
 
@@ -62,6 +64,17 @@ class CommentsController < ApplicationController
   end
 end
 ```
+## How it works
+
+The gem uses a honeypot field and a timestamp token to detect spam submissions:
+
+1. **Honeypot field**: A hidden field that should remain empty. If a bot fills it out, the submission is flagged as spam. Bots often fill out all fields, including hidden ones, while human users do not see them.
+2. **Timestamp token**: A hidden field containing an encrypted timestamp of when the form was rendered. If the form is submitted too quickly (e.g., within a few seconds), it is likely a bot submission. This is encrypted to prevent tampering.
+3. **JavaScript check**: Optionally (using `config.require_js = true`), a JavaScript snippet can be included that sets a flag when the page is fully loaded. If the form is submitted without this flag being set, it indicates that JavaScript was not executed, which is common behavior for bots.
+
+These combined techniques help to effectively reduce spam submissions in web forms. We highly recommend also analysing the message contents (if available) for spammy keywords or patterns as an additional layer of protection.
+
+If you want to take this a step further, consider comibing this gem with a Fail2Ban setup to block IPs that repeatedly trigger spam protections.
 
 ## Configuration
 

data/lib/spam_protect/version.rb

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

data/lib/spam_protect/view_helpers.rb

@@ -2,7 +2,18 @@
 
 module SpamProtect
   module ViewHelpers
-    def spam_protect_javascript_tag
+    # Renders an inline <script> that sets the spam_protect_token cookie.
+    #
+    # @param nonce [String, nil] CSP nonce to include on the script tag.
+    #   Pass `content_security_policy_nonce` if using Rails CSP features.
+    #
+    # @example Without nonce
+    #   <%= spam_protect_javascript_tag %>
+    #
+    # @example With CSP nonce
+    #   <%= spam_protect_javascript_tag(nonce: content_security_policy_nonce) %>
+    #
+    def spam_protect_javascript_tag(nonce: nil)
       payload = Encryption::Payload.generate
       token = Encryption.encrypt(payload.to_h)
 
@@ -13,7 +24,8 @@ module SpamProtect
         })();
       JS
 
-      %(<script>#{js}</script>).html_safe
+      nonce_attr = nonce ? %( nonce="#{ERB::Util.html_escape(nonce)}") : ""
+      %(<script#{nonce_attr}>#{js}</script>).html_safe
     end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: spam_protect
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Full Fat Software
 bindir: bin
 cert_chain: []
-date: 2025-11-14 00:00:00.000000000 Z
+date: 2025-12-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec