otori 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dad6a295086cd2eb7abd60f81e264cde80726e6802deec8e185b3d6ddd2bd082
-  data.tar.gz: b1fe5bab67f24f249b9b45055fa0a632774b99fa93fe0c156235014c9bdf1416
+  metadata.gz: 9139cc5240c7900afc1038f7634429d8cac065d9e22c3645e4891dd9f1fd9103
+  data.tar.gz: d0adef9a1384d5123b7e304879fb9691ebc35e77e238b39a6348419ac8bde074
 SHA512:
-  metadata.gz: a275bbc1f3a7ce4a3f8ae0b6a09b0835aeeca30713254819f747e3e3b06f0c2e8a875a6ca604a8df396ada100ce9518238e8575ec1a06a3bb06e2bec5abe8b5d
-  data.tar.gz: 7fee9a413435e3efcf65f5196fdffe168c664935c8e1390f06545cb9f650571e47e031f04f3f9f2649f01a0b62a67229a9e7071199bdc2903c3dfe1543e625f1
+  metadata.gz: e03586c88e10498d34371303c0d87b09cb8bf643d99e8e30f5b0b19a6ab2851476f6290c547b74d6cfd7c819b281269ccf76d706bc5e42dd03131fa49d4965cf
+  data.tar.gz: 44b8afe56864c015efc19ee2a00ede9167f53bfe471ec7e74ef5ec5d05414522c2835c173e3c5005248447b2241d15c8b1c20e38ed5d4981d986e6d8456ab823

data/CHANGELOG.md

@@ -7,6 +7,50 @@ 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
+
+- `signals_field` now accepts an `id:` attribute. When omitted, a unique id
+  of the form `otori-signals-<hex>` is generated per call so multiple
+  signals fields can safely coexist on the same page.
+
+### Fixed
+
+- `signals_field` no longer relies on
+  `document.currentScript.previousElementSibling` to locate its hidden input.
+  The input now carries a unique `id` and the tracking script looks it up via
+  `document.getElementById`. The previous approach broke when any DOM mutation
+  (Turbo cache restoration, injected elements, browser extensions) landed
+  between the input and the script, which could cause the signals JSON to be
+  written into a neighbouring field (such as a honeypot) and trigger false
+  positives. Callers can supply their own `id:` to override the generated
+  value, and the script now bails out silently when the input or its form
+  cannot be resolved.
+
 ## [0.2.0] - 2026-09-17
 
 ### Added

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/form.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "cgi"
+require "securerandom"
 
 require_relative "validator"
 
@@ -10,20 +11,6 @@ module Otori
 
     HIDDEN_STYLE = "position:absolute;left:-9999px;width:1px;height:1px;pointer-events:none;"
 
-    SIGNALS_SCRIPT = <<~JS
-      (() => {
-        const s = { m: false, t: false, s: false, k: false, f: false };
-        const input = document.currentScript.previousElementSibling;
-        const form = input.form;
-        form.addEventListener('mousemove', () => s.m = true, { once: true });
-        form.addEventListener('touchstart', () => s.t = true, { once: true });
-        form.addEventListener('keydown', () => s.k = true, { once: true });
-        form.addEventListener('focusin', () => s.f = true, { once: true });
-        window.addEventListener('scroll', () => s.s = true, { once: true });
-        form.addEventListener('submit', () => input.value = JSON.stringify(s));
-      })();
-    JS
-
     def field(name, session:, **attrs)
       raise MissingSession unless session_like?(session)
 
@@ -42,16 +29,41 @@ module Otori
     end
 
     def signals_field(**attrs)
+      stringified = stringify_keys(attrs)
+      id = stringified["id"] || generate_signals_id
+
       input = tag(:input, {
-        name: Otori.config.signals_input_name,
-        type: "hidden"
-      }.merge(stringify_keys(attrs)))
+        "id" => id,
+        "name" => Otori.config.signals_input_name,
+        "type" => "hidden"
+      }.merge(stringified))
 
-      "#{input}<script>#{SIGNALS_SCRIPT}</script>"
+      "#{input}<script>#{signals_script(id)}</script>"
     end
 
     private
 
+    def generate_signals_id
+      "otori-signals-#{SecureRandom.hex(6)}"
+    end
+
+    def signals_script(id)
+      <<~JS
+        (() => {
+          const input = document.getElementById(#{id.to_json});
+          if (!input || !input.form) return;
+          const form = input.form;
+          const s = { m: false, t: false, s: false, k: false, f: false };
+          form.addEventListener('mousemove', () => s.m = true, { once: true });
+          form.addEventListener('touchstart', () => s.t = true, { once: true });
+          form.addEventListener('keydown', () => s.k = true, { once: true });
+          form.addEventListener('focusin', () => s.f = true, { once: true });
+          window.addEventListener('scroll', () => s.s = true, { once: true });
+          form.addEventListener('submit', () => input.value = JSON.stringify(s));
+        })();
+      JS
+    end
+
     def session_like?(object)
       object.respond_to?(:[]) && object.respond_to?(:[]=)
     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.2.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.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Wout