otori 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8918f6c816e04317efede4302afa940ac592e92f6a4e8499bd81f9adbee536f0
+  data.tar.gz: c2659d173281ef798d54c52bcd2967dab83d971e3eb662db1ba214565824365a
+SHA512:
+  metadata.gz: fbfb505eb0362b440bdbd0b86f53395dc4f3c1ff059e6446d2d7c8466c93c27f25e9b05889c62962292315bda17fcd09b5b98c434ed613e8bc5858fdf713ca89
+  data.tar.gz: a975548f46af0ec0ceb9d59fb73ef20a175211016156253414676e292f4c08d4b86fa7208aab98ed92ca42b61fc54e97b71f1ddc519dcebeaa61d6fc6b968216

data/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial scaffolding inspired by the
+  [Crystal lucky_honeypot shard](https://codeberg.org/fluck/lucky_honeypot).
+- `Otori::Configuration` with `default_delay`, `disable_delay`, and
+  `signals_input_name`, accessed via `Otori.configure`.
+- `Otori::Form.field` and `Otori::Form.signals_field` for
+  rendering the invisible honeypot input and the input-signals tracker as
+  framework-agnostic HTML strings.
+- `Otori::Signals` for parsing the JSON payload submitted by the
+  tracker and computing a `human_rating` between 0 and 1.
+- `Otori::Validator` with `filled?` and `elapsed?` for the two
+  core form checks.
+- `Otori.caught?` combining the field and timing checks against a
+  session and params hash, with timestamp cleanup on success and reset on
+  failure.
+- `Otori.signals_rating` convenience for computing the human rating
+  straight from a params hash.
+- `Otori::Hanami::Action`, an optional adapter providing a
+  `honeypot` class DSL method that registers a Hanami `before` callback,
+  halting with 204 by default or running a user-supplied block.
+- `Otori::Hanami::Helpers`, an optional view-helper module exposing
+  `honeypot_field` and `honeypot_signals` for Hanami views.
+- `Otori::Error` and `Otori::MissingSession` exception
+  types.
+- Codeberg / Forgejo CI workflow running rspec and rubocop on Ruby 3.4
+  and 4.0.
+- README covering quickstart, framework integration for Hanami, Rails,
+  and any Rack app, configuration, signals interpretation, and security
+  considerations.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wout <hi@wout.codes>
+
+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 above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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,319 @@
+# Otori
+
+[![CI](https://codeberg.org/fluck/otori/actions/workflows/ci.yml/badge.svg)](https://codeberg.org/fluck/otori/actions?workflow=ci.yml)
+[![Version](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fcodeberg.org%2Fapi%2Fv1%2Frepos%2Ffluck%2Fotori%2Ftags&query=%24%5B0%5D.name&label=version)](https://codeberg.org/fluck/otori/tags)
+
+Invisible captcha spam protection for any Rack-based Ruby app, with an opt-in
+Hanami adapter.
+
+_Otori_ (囮) is the Japanese word for "decoy", historically a bird used in
+hunting to draw others in.
+
+This is a Ruby companion to the [Crystal lucky_honeypot
+shard](https://codeberg.org/fluck/lucky_honeypot). It combines three classic
+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.
+
+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
+or flag submissions at a chosen _human rating_ threshold.
+
+> [!NOTE]
+> The original repository is hosted at
+> [Codeberg](https://codeberg.org/fluck/otori). The [GitHub
+> repo](https://github.com/flucksite/otori) is just a mirror.
+
+## Installation
+
+Add this to your Gemfile:
+
+```ruby
+gem "otori"
+```
+
+Then run `bundle install`. Ruby 3.2 or newer is required.
+
+## Quickstart
+
+The gem ships a framework-agnostic core plus an opt-in Hanami adapter. The core
+API is three calls:
+
+```ruby
+Otori.field("user[website]", session: request.session)
+Otori.signals_field
+Otori.caught?("user[website]", params: request.params, session: request.session)
+```
+
+`field` renders the invisible input and stores a load timestamp in the
+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.
+
+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
+honeypot looks next to the real fields, the better.
+
+## Framework integration
+
+### Hanami
+
+The Hanami adapter is loaded explicitly so the base gem stays dependency-free:
+
+```ruby
+require "otori/hanami"
+```
+
+Mix the helpers into your views:
+
+```ruby
+# app/views/helpers.rb
+module MyApp
+  module Views
+    module Helpers
+      include Otori::Hanami::Helpers
+    end
+  end
+end
+```
+
+In a form template:
+
+```erb
+<%= honeypot_field("user[website]") %>
+<%= honeypot_signals %>
+```
+
+The helpers mark their output safe via `String#html_safe`, which Hanami View
+provides out of the box, so the HTML flows through ERB without escaping.
+
+Guard the receiving action with the `honeypot` DSL method:
+
+```ruby
+# app/actions/sign_ups/create.rb
+module MyApp
+  module Actions
+    module SignUps
+      class Create < MyApp::Action
+        include Otori::Hanami::Action
+
+        honeypot "user[website]"
+
+        def handle(request, response)
+          # ...
+        end
+      end
+    end
+  end
+end
+```
+
+When the honeypot is tripped, the action halts with `204 No Content` by
+default. To customize the response, pass a block:
+
+```ruby
+honeypot "user[website]" do |_request, response|
+  response.flash[:info] = "Moving on..."
+  response.redirect_to "/", status: 303
+end
+```
+
+Multiple honeypots are supported, each with its own timing and handler:
+
+```ruby
+honeypot "user[website]", wait: 5
+honeypot "note" do |_req, _res|
+  halt 422
+end
+```
+
+To act on the input-signals rating, evaluate it inside `handle`:
+
+```ruby
+def handle(request, response)
+  rating = Otori.signals_rating(request.params.to_h)
+  halt 204 if rating < 0.4
+
+  # ...
+end
+```
+
+### Rack (Sinatra, Roda, plain Rack)
+
+There is no adapter to require, the core API is enough. In a Sinatra app:
+
+```ruby
+require "otori"
+
+enable :sessions
+
+get "/sign_up" do
+  erb :sign_up
+end
+
+post "/sign_up" do
+  halt 204 if Otori.caught?(
+    "user[website]",
+    params: params,
+    session: session
+  )
+
+  # ...
+end
+```
+
+In the view:
+
+```erb
+<%= Otori.field("user[website]", session: session) %>
+<%= Otori.signals_field %>
+```
+
+### Rails
+
+Rails is well served by [invisible_captcha](https://github.com/markets/invisible_captcha)
+when all you need is a hidden field and a timing check. Use this gem in Rails
+if you want the input-signals rating on top.
+
+```ruby
+# app/helpers/application_helper.rb
+module ApplicationHelper
+  def honeypot_field(name, **attrs)
+    Otori.field(name, session: session, **attrs).html_safe
+  end
+
+  def honeypot_signals(**attrs)
+    Otori.signals_field(**attrs).html_safe
+  end
+end
+```
+
+```ruby
+# app/controllers/sign_ups_controller.rb
+class SignUpsController < ApplicationController
+  before_action :check_honeypot, only: :create
+
+  def create
+    # ...
+  end
+
+  private
+
+  def check_honeypot
+    return unless Otori.caught?(
+      "user[website]",
+      params: params.to_unsafe_h,
+      session: session
+    )
+
+    head :no_content
+  end
+end
+```
+
+## Configuration
+
+```ruby
+Otori.configure do |c|
+  # Required delay (in seconds) between page load and form submission.
+  c.default_delay = 2.0
+
+  # Disables the submission delay entirely. Useful in tests.
+  c.disable_delay = false
+
+  # Name of the hidden input that carries the signals payload.
+  c.signals_input_name = "honeypot_signals"
+end
+```
+
+## The invisible field
+
+By default the field is rendered with an inline `style` attribute that takes
+it out of the visual flow without breaking accessibility tools. Pass your own
+`class` (or `style`) to opt out of the default style and use your CSS instead:
+
+```ruby
+Otori.field("user[website]", session: session, class: "visually-hidden")
+```
+
+Underscored attribute keys are converted to dashes so `data_foo: "bar"`
+renders as `data-foo="bar"`. Any other attribute pair is passed through
+unchanged.
+
+> [!NOTE]
+> The field stores a load timestamp in the session under a
+> `honeypot_field_<name>` key. The companion `caught?` call reads and
+> clears it on success, or resets it when the form is rejected.
+
+## Detecting input signals
+
+`signals_field` renders a hidden input plus a small inline `<script>` that
+listens for the first occurrence of each of five events on the surrounding
+form: `mousemove`, `touchstart`, `keydown`, `focusin`, and a window-level
+`scroll`. On submit, the boolean results are serialized to JSON and posted
+along with the rest of the form.
+
+In the action, get the rating directly from the params:
+
+```ruby
+Otori.signals_rating(params)        # => 0.0 to 1.0
+```
+
+Or work with the parsed object for more detail:
+
+```ruby
+signals = Otori::Signals.from_json(params["honeypot_signals"])
+signals.human_rating  # 0 (bot) to 1 (human)
+signals.mouse?
+signals.touch?
+signals.scroll?
+signals.keyboard?
+signals.focus?
+```
+
+> [!NOTE]
+> The human rating is the fraction of the five signals that fired, so each one
+> contributes `0.2`. A score of `0` is almost certainly a dumb bot, while `0.2`
+> could be a sophisticated bot triggering a single signal (almost always
+> `mouse`), though a human filling out a short form at the top of the page may
+> also land there.
+>
+> `0.4` is a reasonable threshold for flagging entries: it still catches bots
+> that fake one or two signals, but avoids false positives for autofill and
+> password manager submissions, which often only trigger focus plus mouse or
+> touch.
+
+## Security considerations
+
+This gem provides basic bot protection, but it should not be your only line
+of defense.
+
+- It is not foolproof, sophisticated bots can bypass honeypots.
+- Combine this with a rate limiter such as `rack-attack`.
+- For high-value forms, consider adding CAPTCHA or email verification.
+- The submission timestamp is stored in the session. If sessions are
+  compromised, an attacker could manipulate timing checks. Make sure your session
+  store uses signed and encrypted cookies.
+- The timing check compares wall-clock timestamps, which makes it resilient to
+  timing attacks since the check is a simple threshold comparison.
+- This gem does not touch CSRF tokens. Honeypot fields are regular form inputs
+  and do not interfere with your framework's CSRF protection.
+
+For most use cases (contact forms, newsletter signups), this gem provides solid
+protection with zero user friction. Expect it to catch between 60% and 90% of
+automated form submissions.
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT

data/lib/otori/configuration.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Otori
+  class Configuration
+    SESSION_KEY_PREFIX = "honeypot_field"
+
+    attr_accessor :default_delay, :disable_delay, :signals_input_name
+
+    def initialize
+      @default_delay = 2.0
+      @disable_delay = false
+      @signals_input_name = "honeypot_signals"
+    end
+
+    def session_key(name)
+      safe = name.to_s.gsub(/[^a-z0-9_]+/i, "_").gsub(/\A_+|_+\z/, "")
+      "#{SESSION_KEY_PREFIX}_#{safe}"
+    end
+  end
+end

data/lib/otori/error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Otori
+  class Error < StandardError; end
+
+  class MissingSession < Error
+    def initialize
+      super(
+        "Otori needs a session-like object (responding to []=, []) " \
+          "to store the form-load timestamp. Enable sessions in your app."
+      )
+    end
+  end
+end

data/lib/otori/form.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+require_relative "validator"
+
+module Otori
+  module Form
+    extend self
+
+    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)
+
+      session[Otori.config.session_key(name)] = Validator.monotonic_ms.to_s
+
+      base = {
+        name: name.to_s,
+        type: "text",
+        "aria-hidden": "true",
+        tabindex: "-1",
+        autocomplete: "off"
+      }
+      base[:style] = HIDDEN_STYLE unless attrs.key?(:class) || attrs.key?(:style)
+
+      tag(:input, base.merge(stringify_keys(attrs)))
+    end
+
+    def signals_field(**attrs)
+      input = tag(:input, {
+        name: Otori.config.signals_input_name,
+        type: "hidden"
+      }.merge(stringify_keys(attrs)))
+
+      "#{input}<script>#{SIGNALS_SCRIPT}</script>"
+    end
+
+    private
+
+    def session_like?(object)
+      object.respond_to?(:[]) && object.respond_to?(:[]=)
+    end
+
+    def stringify_keys(attrs)
+      attrs.to_h { |key, value| [key.to_s.tr("_", "-"), value] }
+    end
+
+    def tag(name, attrs)
+      pairs = attrs.compact.map do |key, value|
+        next CGI.escape_html(key.to_s) if value == true
+
+        %(#{CGI.escape_html(key.to_s)}="#{CGI.escape_html(value.to_s)}")
+      end
+      "<#{name} #{pairs.join(" ")}>"
+    end
+  end
+end

data/lib/otori/hanami.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../otori"
+
+module Otori
+  module Hanami
+    module Action
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def honeypot(name, wait: nil, &on_caught)
+          field_name = name
+          field_wait = wait
+          caught_block = on_caught
+
+          before do |request, response|
+            next unless Otori.caught?(
+              field_name,
+              params: request.params.to_h,
+              session: request.session,
+              wait: field_wait
+            )
+
+            if caught_block
+              instance_exec(request, response, &caught_block)
+            else
+              halt 204
+            end
+          end
+        end
+      end
+    end
+
+    module Helpers
+      def honeypot_field(name, **attrs)
+        Otori.field(name, session: _otori_session, **attrs).html_safe
+      end
+
+      def honeypot_signals(**attrs)
+        Otori.signals_field(**attrs).html_safe
+      end
+
+      private
+
+      def _otori_session
+        return context.request.session if respond_to?(:context) &&
+                                          context.respond_to?(:request)
+        return request.session if respond_to?(:request)
+
+        raise Otori::MissingSession
+      end
+    end
+  end
+end

data/lib/otori/signals.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Otori
+  class Signals
+    KEYS = {
+      mouse: "m",
+      touch: "t",
+      scroll: "s",
+      keyboard: "k",
+      focus: "f"
+    }.freeze
+
+    def self.from_json(json)
+      raw = JSON.parse(json.to_s)
+      raise JSON::ParserError, "expected an object" unless raw.is_a?(Hash)
+
+      new(KEYS.transform_values { raw[_1] == true })
+    rescue JSON::ParserError
+      new
+    end
+
+    def self.human_rating(json)
+      from_json(json).human_rating
+    end
+
+    def initialize(flags = {})
+      @flags = KEYS.keys.to_h { [_1, flags.fetch(_1, false) == true] }
+    end
+
+    KEYS.each_key do |key|
+      define_method("#{key}?") { @flags.fetch(key) }
+    end
+
+    def human_rating
+      @flags.values.count(true) / KEYS.size.to_f
+    end
+
+    def to_h = @flags.dup
+  end
+end

data/lib/otori/validator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Otori
+  module Validator
+    extend self
+
+    def filled?(value)
+      !value.nil? && !value.to_s.strip.empty?
+    end
+
+    def elapsed?(timestamp_ms, wait_seconds, now: monotonic_ms)
+      return true if Otori.config.disable_delay
+      return false if timestamp_ms.nil?
+
+      (now - timestamp_ms.to_i) >= (wait_seconds.to_f * 1000)
+    end
+
+    def monotonic_ms = (Time.now.to_f * 1000).to_i
+  end
+end

data/lib/otori/version.rb

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

data/lib/otori.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require_relative "otori/version"
+require_relative "otori/error"
+require_relative "otori/configuration"
+require_relative "otori/signals"
+require_relative "otori/validator"
+require_relative "otori/form"
+
+module Otori
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+      config
+    end
+
+    def reset_config!
+      @config = Configuration.new
+    end
+
+    def field(name, session:, **attrs)
+      Form.field(name, session: session, **attrs)
+    end
+
+    def signals_field(**attrs)
+      Form.signals_field(**attrs)
+    end
+
+    def caught?(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
+        session[session_key] = Validator.monotonic_ms.to_s
+        true
+      end
+    end
+
+    def signals_rating(params)
+      raw = param_value(params, config.signals_input_name)
+      return 0.0 if raw.nil? || raw.to_s.empty?
+
+      Signals.human_rating(raw.to_s)
+    end
+
+    private
+
+    def param_value(params, name)
+      param_keys(name).reduce(params) do |scope, key|
+        break nil unless scope.respond_to?(:[])
+
+        scope[key] || scope[key.to_sym]
+      end
+    end
+
+    def param_keys(name)
+      keys = name.to_s.scan(/[^\[\]]+/)
+      keys.empty? ? [name.to_s] : keys
+    end
+
+    def session_get(session, key)
+      session[key] || session[key.to_sym]
+    end
+
+    def session_delete(session, key)
+      session.delete(key) if session.respond_to?(:delete)
+    end
+  end
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: otori
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Wout
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Drop-in honeypot spam protection for any Rack-based app. Combines an
+  invisible form field, a submission-timing check, and a JavaScript input
+  signals tracker (mouse, touch, scroll, keyboard, focus) into a single
+  framework-agnostic gem, with an opt-in Hanami adapter. Ruby companion to
+  the Crystal lucky_honeypot shard.
+email:
+- hi@wout.codes
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/otori.rb
+- lib/otori/configuration.rb
+- lib/otori/error.rb
+- lib/otori/form.rb
+- lib/otori/hanami.rb
+- lib/otori/signals.rb
+- lib/otori/validator.rb
+- lib/otori/version.rb
+homepage: https://codeberg.org/fluck/otori
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://codeberg.org/fluck/otori
+  bug_tracker_uri: https://codeberg.org/fluck/otori/issues
+  changelog_uri: https://codeberg.org/fluck/otori/src/branch/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.11
+specification_version: 4
+summary: Invisible honeypot spam protection for Rack apps, with a Hanami adapter.
+test_files: []