otori 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be91dcf0d80421c3347a3d75e9e7aade7a7479f8e7b100c6d628f394016c2d37
-  data.tar.gz: d8bd1c71cb521c22f5f9797612cd83105bef897584d1a92d3004acaad7625b73
+  metadata.gz: 9139cc5240c7900afc1038f7634429d8cac065d9e22c3645e4891dd9f1fd9103
+  data.tar.gz: d0adef9a1384d5123b7e304879fb9691ebc35e77e238b39a6348419ac8bde074
 SHA512:
-  metadata.gz: 7dbcb90604352965d8f951c2caf025978deafb6e8b23772cafb953a0fba20a2f3a292567ffa48441a0fb82a9794a4c5abb3d82297cfc824effa11bbc8c65bf25
-  data.tar.gz: 2c0df32a81ca7fdce8234e91d52b10379e8931b597732f54de8393c0460409ecd50a5bbe01551a876dd12711fd4ee6db63a12197128db0ad53fb59a157ec18c6
+  metadata.gz: e03586c88e10498d34371303c0d87b09cb8bf643d99e8e30f5b0b19a6ab2851476f6290c547b74d6cfd7c819b281269ccf76d706bc5e42dd03131fa49d4965cf
+  data.tar.gz: 44b8afe56864c015efc19ee2a00ede9167f53bfe471ec7e74ef5ec5d05414522c2835c173e3c5005248447b2241d15c8b1c20e38ed5d4981d986e6d8456ab823

data/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-13
+
+### Added
+
+- `Otori.reason` returns the specific catch reason as a symbol
+  (`:filled` when the honeypot field was filled, `:too_fast` when the
+  form was submitted before the configured delay elapsed, `nil` when the
+  submission looks clean). This lets callers distinguish genuinely
+  suspicious submissions from users who merely autofilled and submitted
+  faster than the delay allows.
+- The Rails adapter's `on_caught` block now receives the reason symbol
+  as its sole argument, so applications can log, flag, or branch on it
+  (`honeypot(:website) { |reason| ... }`). Zero-arg blocks continue to
+  work unchanged.
+- The Hanami adapter's `on_caught` block now receives the reason symbol
+  as a third argument after `request` and `response`. Two-arg blocks
+  continue to work unchanged.
+
+### Changed
+
+- `Otori.caught?` is now a thin predicate over `Otori.reason`. Its
+  return value and session side effects are unchanged.
+
 ## [0.3.0] - 2026-10-12
 
 ### Changed

data/README.md

@@ -78,6 +78,20 @@ session. `signals_field` renders a hidden input plus the JavaScript that
 tracks human input. `caught?` checks the submitted form and returns `true`
 when the request looks like a bot.
 
+If you want to know _why_ a submission was caught (for logging, flagging,
+or scoring), use `Otori.reason`:
+
+```ruby
+Otori.reason("user[website]", params: request.params, session: request.session)
+# => :filled    when the honeypot field was filled
+# => :too_fast  when the form was submitted before the delay elapsed
+# => nil        when the submission looks clean
+```
+
+`caught?` is implemented as `!reason(...).nil?`. Both methods perform the
+same session timestamp bookkeeping, so pick one and stick with it per
+request.
+
 Field names use standard HTML bracket notation, so `"user[website]"` lives
 under `params[:user][:website]` once submitted. Flat names like `"note"` work
 too. Pick whichever fits the surrounding form, the more believable the
@@ -138,10 +152,13 @@ end
 ```
 
 When the honeypot is tripped, the action halts with `204 No Content` by
-default. To customize the response, pass a block:
+default. To customize the response, pass a block. The block optionally
+receives the catch reason (`:filled` or `:too_fast`) as a third argument,
+handy for logging or branching:
 
 ```ruby
-honeypot "user[website]" do |_request, response|
+honeypot "user[website]" do |_request, response, reason|
+  SecurityLog.record!(reason: reason)
   response.flash[:info] = "Moving on..."
   response.redirect_to "/", status: 303
 end
@@ -227,10 +244,12 @@ end
 ```
 
 When the honeypot is tripped, the request halts with `:no_content` by default.
-To customize the response, pass a block:
+To customize the response, pass a block. The block optionally receives the
+catch reason (`:filled` or `:too_fast`), handy for logging or branching:
 
 ```ruby
-honeypot :website, only: :create do
+honeypot :website, only: :create do |reason|
+  SecurityLog.record!(reason: reason)
   redirect_to root_path, notice: "Moving on..."
 end
 ```

data/lib/otori/hanami.rb

@@ -16,15 +16,16 @@ module Otori
           caught_block = on_caught
 
           before do |request, response|
-            next unless Otori.caught?(
+            reason = Otori.reason(
               field_name,
               params: request.params.to_h,
               session: request.session,
               wait: field_wait
             )
+            next unless reason
 
             if caught_block
-              instance_exec(request, response, &caught_block)
+              instance_exec(request, response, reason, &caught_block)
             else
               halt 204
             end

data/lib/otori/rails.rb

@@ -11,15 +11,11 @@ module Otori
         filter_options[:except] = except if except
 
         before_action(**filter_options) do
-          next unless Otori.caught?(
-            name,
-            params:,
-            session:,
-            wait:
-          )
+          reason = Otori.reason(name, params:, session:, wait:)
+          next unless reason
 
           if on_caught
-            instance_exec(&on_caught)
+            instance_exec(reason, &on_caught)
           else
             head :no_content
           end

data/lib/otori/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Otori
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/otori.rb

@@ -31,19 +31,23 @@ module Otori
     end
 
     def caught?(name, params:, session:, wait: nil)
+      !reason(name, params:, session:, wait:).nil?
+    end
+
+    def reason(name, params:, session:, wait: nil)
       wait ||= config.default_delay
       session_key = config.session_key(name)
       stored = session_get(session, session_key)
       filled = Validator.filled?(param_value(params, name))
       elapsed = Validator.elapsed?(stored&.to_i, wait)
 
-      if !filled && elapsed
-        session_delete(session, session_key)
-        false
-      else
+      caught = catch_reason(filled:, elapsed:)
+      if caught
         session[session_key] = Validator.monotonic_ms.to_s
-        true
+      else
+        session_delete(session, session_key)
       end
+      caught
     end
 
     def signals_rating(params)
@@ -55,6 +59,13 @@ module Otori
 
     private
 
+    def catch_reason(filled:, elapsed:)
+      return :filled if filled
+      return :too_fast unless elapsed
+
+      nil
+    end
+
     def param_value(params, name)
       param_keys(name).reduce(params) do |scope, key|
         break nil unless scope.respond_to?(:[])

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: otori
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Wout