otori 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be91dcf0d80421c3347a3d75e9e7aade7a7479f8e7b100c6d628f394016c2d37
-  data.tar.gz: d8bd1c71cb521c22f5f9797612cd83105bef897584d1a92d3004acaad7625b73
+  metadata.gz: 7d06214bc12e9ac02bb0989a000bbf68987a12cc15d0a3c178a1fffcfd92503f
+  data.tar.gz: 474f1fb57b296c594d22fb4c00126658c9209fe0f8c10a323b0f34c014893e26
 SHA512:
-  metadata.gz: 7dbcb90604352965d8f951c2caf025978deafb6e8b23772cafb953a0fba20a2f3a292567ffa48441a0fb82a9794a4c5abb3d82297cfc824effa11bbc8c65bf25
-  data.tar.gz: 2c0df32a81ca7fdce8234e91d52b10379e8931b597732f54de8393c0460409ecd50a5bbe01551a876dd12711fd4ee6db63a12197128db0ad53fb59a157ec18c6
+  metadata.gz: f58ff908079e04df4436fcf0266e22cc1453c020a295f4e2fe6f0317664efd587ec7e2dbf45c6492035823ec212414a86939aab81d7176fb595bf65fba4d4fcc
+  data.tar.gz: 686f43334060ddc3067be606224c9b07b5a1e1fefc6519faa3e75cc1fc572f4967909d60ea08b32f35c53053408b6dfd79dd71e7c29067387e49c94fb4899e93

data/CHANGELOG.md

@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-13
+
+### Added
+
+- Passing `wait: false` to `Otori.reason` / `Otori.caught?` (and the
+  Rails/Hanami `honeypot` macros) skips the timing check entirely while
+  keeping the filled-field check active. Useful for forms where
+  password-manager autofill or sticky-session returns make even a short
+  timer prone to false positives. `wait: nil` continues to fall back to
+  `config.default_delay`; only an explicit `false` disables timing.
+
+## [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

@@ -18,7 +18,8 @@ techniques into one gem:
 
 1. **Invisible fields**. Bots fill out every field, including ones hidden with CSS.
 2. **Timing checks**. Bots submit forms instantly, humans need more time.
-3. **Input signals**. Bots don't tend to trigger mouse, touch, scroll, keyboard, or focus events.
+3. **Input signals**. Bots don't tend to trigger mouse, touch, scroll,
+   keyboard, or focus events.
 
 When either of the first two checks fail, the submission is quietly rejected.
 The bot thinks it succeeded and moves on. The third one can be used to reject
@@ -78,6 +79,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 +153,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
@@ -156,6 +174,14 @@ honeypot "note" do |_req, _res|
 end
 ```
 
+Pass `wait: false` to skip the timing check entirely while keeping the
+filled-field check active. Useful on login or password-reset forms where
+password-manager autofill routinely beats any reasonable timer:
+
+```ruby
+honeypot "user[website]", wait: false
+```
+
 To act on the input-signals rating, evaluate it inside `handle`:
 
 ```ruby
@@ -226,11 +252,21 @@ class SignUpsController < ApplicationController
 end
 ```
 
+Pass `wait: false` to skip the timing check entirely while keeping the
+filled-field check active. Useful on forms where password-manager autofill
+beats any reasonable timer (login, password reset):
+
+```ruby
+honeypot :username, wait: false, only: :create
+```
+
 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/validator.rb

@@ -10,6 +10,7 @@ module Otori
 
     def elapsed?(timestamp_ms, wait_seconds, now: monotonic_ms)
       return true if Otori.config.disable_delay
+      return true if wait_seconds == false
       return false if timestamp_ms.nil?
 
       (now - timestamp_ms.to_i) >= (wait_seconds.to_f * 1000)

data/lib/otori/version.rb

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

data/lib/otori.rb

@@ -31,19 +31,23 @@ module Otori
     end
 
     def caught?(name, params:, session:, wait: nil)
-      wait ||= config.default_delay
+      !reason(name, params:, session:, wait:).nil?
+    end
+
+    def reason(name, params:, session:, wait: nil)
+      wait = config.default_delay if wait.nil?
       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.5.0
 platform: ruby
 authors:
 - Wout