spamtrap 0.3.5 → 0.4.3

data/lib/spamtrap/helper.rb

@@ -1,6 +1,10 @@
 # frozen_string_literal: true
 
 module Spamtrap
+  # Raised by spamtrap_nonce_fields when there's no request to bind the nonce to
+  # (mailers, ApplicationController.render outside a request, etc.).
+  class NoRequestError < StandardError; end
+
   module FormBuilderMutation
     include Spamtrap::Crypto
 
@@ -9,12 +13,15 @@ module Spamtrap
       text_area check_box hidden_field file_field date_field time_field
       datetime_local_field month_field week_field search_field color_field
       range_field select collection_select grouped_collection_select label
+      radio_button phone_field datetime_field time_zone_select weekday_select
+      collection_check_boxes collection_radio_buttons date_select time_select
+      datetime_select rich_text_area
     ].freeze
 
     MUTABLE_FIELDS.each do |m|
       define_method(m) do |field, *args, &blk|
-        if @spamtrap_salt
-          encrypted_field = spamtrap_encrypt_field(field.to_s, @spamtrap_salt)
+        if @spamtrap_timestamp
+          encrypted_field = spamtrap_token_for(field)
 
           opts =
             if m == :check_box
@@ -25,49 +32,102 @@ module Spamtrap
 
           model_value = object.respond_to?(field) ? object.public_send(field) : nil
 
-          case m
-          when :check_box
-            # :checked controls the checked state; :value is the submitted value ("1" by default)
-            opts[:checked] = !!model_value unless opts.key?(:checked)
-            super(encrypted_field, opts, *args, &blk)
-          when :select, :collection_select, :grouped_collection_select
-            # :selected belongs in the inner options hash, not html_options (the last hash).
-            # After popping html_options into opts, args.last is the options hash (if present).
-            if args.last.is_a?(Hash)
-              sel_opts = args.pop.dup
-              sel_opts[:selected] = model_value unless sel_opts.key?(:selected)
-              args.push(sel_opts)
+          html =
+            case m
+            when :check_box
+              spamtrap_apply_model_value(m, opts, model_value)
+              opts[:id] = field_id(field) if Spamtrap.stable_ids && !opts.key?(:id)
+              super(encrypted_field, opts, *args, &blk)
+            when :radio_button
+              tag_value = args.first
+              spamtrap_apply_model_value(m, opts, model_value, tag_value)
+              opts[:id] = spamtrap_radio_id(field, tag_value) if Spamtrap.stable_ids && !opts.key?(:id)
+              super(encrypted_field, *args, opts, &blk)
+            when :select, :collection_select, :grouped_collection_select, :weekday_select
+              # :selected belongs in the inner options hash, not html_options (the last hash).
+              # After popping html_options into opts, args.last is the options hash (if present).
+              if args.last.is_a?(Hash)
+                sel_opts = args.pop.dup
+                spamtrap_apply_model_value(m, sel_opts, model_value)
+                args.push(sel_opts)
+              else
+                spamtrap_apply_model_value(m, opts, model_value)
+              end
+              opts[:id] = field_id(field) if Spamtrap.stable_ids && !opts.key?(:id)
+              super(encrypted_field, *args, opts, &blk)
+            when :time_zone_select
+              # Unlike the others above, priority_zones sits before options; pad it back in
+              # when the caller omitted it entirely so opts lands as options, not priority_zones.
+              if args.last.is_a?(Hash)
+                sel_opts = args.pop.dup
+                spamtrap_apply_model_value(m, sel_opts, model_value)
+                args.push(sel_opts)
+              else
+                args.push(nil) if args.empty?
+                spamtrap_apply_model_value(m, opts, model_value)
+              end
+              opts[:id] = field_id(field) if Spamtrap.stable_ids && !opts.key?(:id)
+              super(encrypted_field, *args, opts, &blk)
+            when :collection_check_boxes, :collection_radio_buttons
+              # Rails computes each collection item's own <input> id internally; left opaque.
+              if args.last.is_a?(Hash)
+                sel_opts = args.pop.dup
+                spamtrap_apply_model_value(m, sel_opts, model_value)
+                args.push(sel_opts)
+              else
+                spamtrap_apply_model_value(m, opts, model_value)
+              end
+              super(encrypted_field, *args, opts, &blk)
+            when :date_select, :time_select, :datetime_select
+              # Rails derives each <select>'s id from its multiparameter suffix (e.g. "(1i)"); left opaque.
+              if args.last.is_a?(Hash)
+                sel_opts = args.pop.dup
+                spamtrap_apply_model_value(m, sel_opts, model_value)
+                args.push(sel_opts)
+              else
+                spamtrap_apply_model_value(m, opts, model_value)
+              end
+              super(encrypted_field, *args, opts, &blk)
+            when :label
+              # Preserve the human-readable label text using the real field name
+              # before substituting the encrypted form. Mirrors Rails' own
+              # resolution order:
+              #   1. explicit text argument — kept as-is
+              #   2. activerecord.attributes.Model.field (ActiveRecord models)
+              #   3. helpers.label.object_name.field (plain objects / form_with)
+              #   4. humanize fallback
+              # Discard any explicit nil that a subclass may have passed through
+              # (e.g. `super(method, nil, options)`) so it does not survive as a
+              # spurious positional argument in the final super call.
+              args.compact!
+              unless args.first.is_a?(String)
+                human_text =
+                  if object.respond_to?(:to_model)
+                    object.class.human_attribute_name(field.to_s, default: field.to_s.humanize)
+                  else
+                    I18n.t(field, scope: [:helpers, :label, object_name], default: field.to_s.humanize)
+                  end
+                args.unshift(human_text)
+              end
+              opts[:for] = field_id(field) if Spamtrap.stable_ids && !opts.key?(:for)
+              super(encrypted_field, *args, opts, &blk)
+            when :rich_text_area
+              # Action Text may not be loaded, so FormBuilder won't define this method at all;
+              # `super` would then raise a confusing "super: no superclass method" instead of
+              # a normal NoMethodError naming the method the caller actually tried to call.
+              spamtrap_apply_model_value(m, opts, model_value)
+              if defined?(super)
+                super(encrypted_field, *args, opts, &blk)
+              else
+                raise NoMethodError, "undefined method `#{m}' for an instance of #{self.class}"
+              end
             else
-              opts[:selected] = model_value unless opts.key?(:selected)
+              spamtrap_apply_model_value(m, opts, model_value)
+              opts[:id] = field_id(field) if Spamtrap.stable_ids && !opts.key?(:id)
+              super(encrypted_field, *args, opts, &blk)
             end
 
-            super(encrypted_field, *args, opts, &blk)
-          when :label
-            # Preserve the human-readable label text using the real field name
-            # before substituting the encrypted form. Mirrors Rails' own
-            # resolution order:
-            #   1. explicit text argument — kept as-is
-            #   2. activerecord.attributes.Model.field (ActiveRecord models)
-            #   3. helpers.label.object_name.field (plain objects / form_with)
-            #   4. humanize fallback
-            # Discard any explicit nil that a subclass may have passed through
-            # (e.g. `super(method, nil, options)`) so it does not survive as a
-            # spurious positional argument in the final super call.
-            args.compact!
-            unless args.first.is_a?(String)
-              human_text =
-                if object.respond_to?(:to_model)
-                  object.class.human_attribute_name(field.to_s, default: field.to_s.humanize)
-                else
-                  I18n.t(field, scope: [:helpers, :label, object_name], default: field.to_s.humanize)
-                end
-              args.unshift(human_text)
-            end
-            super(encrypted_field, *args, opts, &blk)
-          else
-            opts[:value] = model_value unless opts.key?(:value)
-            super(encrypted_field, *args, opts, &blk)
-          end
+          spamtrap_error_wrap(html, field)
         else
           super(field, *args, &blk)
         end
@@ -76,51 +136,174 @@ module Spamtrap
 
     def initialize(object_name, object, template, options)
       super
-      @spamtrap_salt = options[:spamtrap_salt] if options[:spamtrap_salt]
+      @spamtrap_options = options[:spamtrap] if options[:spamtrap].is_a?(Hash)
+      @spamtrap_timestamp = options[:spamtrap_timestamp] if options[:spamtrap_timestamp]
+      @spamtrap_tokens    = options[:spamtrap_tokens]    if options[:spamtrap_tokens]
+      # A fields_for child inherits its parent's already-computed context (may legitimately be nil).
+      @spamtrap_context   = options[:spamtrap_context]   if options.key?(:spamtrap_context)
+      # Mint the shared timestamp up front so mutation works no matter where f.spamtrap
+      # is called in the form (or if it's never called at all).
+      @spamtrap_timestamp ||= Time.now.to_i if @spamtrap_options && @spamtrap_options[:mutate]
     end
 
     def fields_for(record_name, record_object = nil, fields_options = {}, &block)
-      if @spamtrap_salt
+      if @spamtrap_timestamp
+        # Children share the parent's token cache: indexless `items[][name]` arrays only split
+        # into separate records when the same field name repeats as the same key. spamtrap_context
+        # is computed here (not left lazy) so a child never needs its own request.
+        shared = { spamtrap_timestamp: @spamtrap_timestamp, spamtrap_tokens: (@spamtrap_tokens ||= {}), spamtrap_context: spamtrap_context }
         if record_object.is_a?(Hash) && record_object.extractable_options?
-          record_object = record_object.merge(spamtrap_salt: @spamtrap_salt)
+          record_object = record_object.merge(shared)
         else
-          fields_options = fields_options.merge(spamtrap_salt: @spamtrap_salt)
+          fields_options = fields_options.merge(shared)
         end
       end
       super(record_name, record_object, fields_options, &block)
     end
+
+    private
+
+    # One token per field name per render (shared with fields_for children), or a fresh IV per
+    # call would make <label for> and <input id> mismatch and split indexless array records.
+    def spamtrap_token_for(field)
+      @spamtrap_tokens ||= {}
+      @spamtrap_tokens[field.to_s] ||= spamtrap_encrypt_field(field.to_s, spamtrap_aad(@spamtrap_timestamp, spamtrap_context))
+    end
+
+    # Memoized per builder (nil is a legitimate result when Spamtrap.token_context is unset),
+    # so every token this builder mints — mutation, nonce, js proof — binds to the same context.
+    def spamtrap_context
+      return @spamtrap_context if defined?(@spamtrap_context)
+
+      @spamtrap_context =
+        if Spamtrap.token_context
+          unless @template.respond_to?(:request) && @template.request
+            raise Spamtrap::NoRequestError, 'Spamtrap.token_context needs a request; render the form inside a request or unset Spamtrap.token_context'
+          end
+          Spamtrap.token_context_for(@template.request)
+        end
+    end
+
+    # Fills in the key each helper reads its pre-filled state from (:value, :checked,
+    # :selected...), unless the caller already gave one explicitly.
+    def spamtrap_apply_model_value(m, target, model_value, tag_value = nil)
+      # Some tags (Rails 8.1 date/time fields, time_zone_select, weekday_select) read the
+      # model value eagerly via the encrypted method name; this tells Rails to return nil
+      # instead of raising. Rails deletes the key, so it never reaches the HTML.
+      target[:allow_method_names_outside_object] = true unless target.key?(:allow_method_names_outside_object)
+
+      case m
+      when :check_box
+        target[:checked] = !!model_value unless target.key?(:checked)
+      when :radio_button
+        target[:checked] = (model_value.to_s == tag_value.to_s) unless target.key?(:checked)
+      when :select, :collection_select, :grouped_collection_select, :weekday_select
+        target[:selected] = model_value unless target.key?(:selected)
+      when :time_zone_select
+        # Unlike the others, TimeZoneSelect falls back to :default, not :selected.
+        target[:default] = model_value unless target.key?(:default)
+      when :collection_check_boxes, :collection_radio_buttons
+        target[:checked] = model_value unless target.key?(:checked)
+      when :date_select, :time_select, :datetime_select
+        target[:selected] = model_value unless target.key?(:selected) || target.key?(:default) || model_value.nil?
+      else
+        target[:value] = model_value unless target.key?(:value)
+      end
+    end
+
+    # Mirrors ActionView::Helpers::Tags::Base#sanitized_value so a radio button's id is
+    # identical to what an unmutated render would produce, just rooted at the real field name.
+    def spamtrap_radio_id(field, tag_value)
+      suffix = tag_value.to_s.gsub(/[\s.]/, '_').gsub(/[^-[[:word:]]]/, '').downcase
+      field_id(field, suffix)
+    end
+
+    # Rails looks up object.errors[method] using the (encrypted) method name it was given,
+    # which never has errors for a mutated field, so field_with_errors silently stops
+    # applying. Replicate it here using the real field name instead.
+    def spamtrap_error_wrap(html, field)
+      return html unless object.respond_to?(:errors) && object.errors[field].present?
+
+      tag_stub = Struct.new(:object, :method_name, :error_message).new(object, field.to_s, object.errors[field])
+      @template.instance_exec(html, tag_stub, &ActionView::Base.field_error_proc)
+    end
   end
 end
 
-class ActionView::Helpers::FormBuilder
-  prepend Spamtrap::FormBuilderMutation
-
+# The f.spamtrap helper. Mixed into ActionView::Helpers::FormBuilder by Spamtrap.install!
+# (via the Railtie in a Rails app) rather than by reopening the class at require time.
+module Spamtrap::FormBuilderHelper
   def spamtrap(parameter = 'spamtrap', options = {})
-    mutate = options.key?(:mutate) ? options.delete(:mutate) : Spamtrap.mutate
-    nonce  = options.key?(:nonce)  ? options.delete(:nonce)  : Spamtrap.nonce
-    options.reverse_merge!(class: 'spamtrap')
-
-    if mutate
-      @spamtrap_salt = SecureRandom.bytes(Spamtrap::Crypto::NONCE_LEN)
-      salt_field = @template.hidden_field_tag(
-        :spamtrap_mutation_salt, @spamtrap_salt.unpack1('H*')
-      )
-    end
+    mutate   = options.key?(:mutate)        ? options.delete(:mutate)        : spamtrap_option_default(:mutate)
+    nonce    = options.key?(:nonce)         ? options.delete(:nonce)         : spamtrap_option_default(:nonce)
+    bind_ip  = options.key?(:nonce_bind_ip) ? options.delete(:nonce_bind_ip) : spamtrap_option_default(:nonce_bind_ip)
+    styles   = Array(options.key?(:styles) ? options.delete(:styles) : spamtrap_option_default(:styles))
+    js_proof = options.key?(:js_proof)      ? options.delete(:js_proof)      : spamtrap_option_default(:js_proof)
+    options.reverse_merge!(class: 'spamtrap', tabindex: -1, autocomplete: 'off', 'aria-hidden' => true, style: 'display:none')
 
-    @template.text_area_tag(parameter, nil, options) +
-      (nonce ? spamtrap_nonce_fields : ''.html_safe) +
-      (salt_field || ''.html_safe)
+    # One timestamp per render, shared by mutation tokens, the nonce HMAC, and js_proof, so the
+    # hidden field is emitted once no matter which subset of these features is on. Reuse the
+    # timestamp already minted at builder construction (spamtrap: { mutate: true }) instead of a fresh one.
+    timestamp = @spamtrap_timestamp || (Time.now.to_i if mutate || nonce || js_proof)
+    @spamtrap_timestamp = timestamp if mutate
+
+    spamtrap_honeypot_tags(parameter, styles, options) +
+      ((mutate || nonce || js_proof) ? @template.hidden_field_tag(:spamtrap_timestamp, timestamp) : ''.html_safe) +
+      (nonce ? spamtrap_nonce_fields(timestamp, parameter.to_s, bind_ip) : ''.html_safe) +
+      (js_proof ? spamtrap_js_tags(timestamp, parameter.to_s) : ''.html_safe)
   end
 
   private
 
-  def spamtrap_nonce_fields
-    timestamp = Time.now.to_i
-    ip        = @template.request.remote_ip
-    secret    = Rails.application.secret_key_base
-    nonce     = OpenSSL::HMAC.hexdigest('SHA256', secret, "#{timestamp}:#{ip}")
+  def spamtrap_option_default(key)
+    if @spamtrap_options&.key?(key)
+      @spamtrap_options[key]
+    else
+      # :styles has no same-named Spamtrap global; it maps to honeypot_styles instead.
+      Spamtrap.public_send(key == :styles ? :honeypot_styles : key)
+    end
+  end
+
+  # One decoy per requested style, all sharing the same hiding options; each decoy's own name
+  # is mutated (see spamtrap_token_for) exactly like the classic textarea's is.
+  def spamtrap_honeypot_tags(parameter, styles, options)
+    field_names = Spamtrap.honeypot_fields(parameter)
+
+    styles.map do |style|
+      raise ArgumentError, "unknown spamtrap honeypot style: #{style.inspect}" unless field_names.key?(style)
+
+      name = @spamtrap_timestamp ? spamtrap_token_for(field_names[style]) : field_names[style]
 
-    @template.hidden_field_tag(:spamtrap_timestamp, timestamp) +
+      case style
+      when :textarea then @template.text_area_tag(name, nil, options)
+      when :text      then @template.text_field_tag(name, nil, options)
+      when :checkbox  then @template.check_box_tag(name, '1', false, options)
+      end
+    end.inject(:+)
+  end
+
+  def spamtrap_nonce_fields(timestamp, honeypot, bind_ip)
+    unless @template.respond_to?(:request) && @template.request
+      raise Spamtrap::NoRequestError, 'Spamtrap nonce fields need a request; render the form inside a request or pass nonce: false'
+    end
+
+    ip       = @template.request.remote_ip
+    nonce_id = SecureRandom.hex(16)
+    nonce    = spamtrap_nonce_digest(timestamp, ip, honeypot, nonce_id, bind_ip: bind_ip, context: spamtrap_context)
+
+    @template.hidden_field_tag(:spamtrap_nonce_id, nonce_id) +
       @template.hidden_field_tag(:spamtrap_nonce, nonce)
   end
+
+  # A hidden field only an executing script fills in, plus the inline script that fills it.
+  # javascript_tag(nonce: true) attaches a CSP nonce automatically when the app configures one.
+  def spamtrap_js_tags(timestamp, honeypot)
+    id     = "spamtrap_js_#{SecureRandom.hex(4)}"
+    digest = spamtrap_js_digest(timestamp, honeypot, context: spamtrap_context)
+    # Embedded reversed so a naive regex scrape of the page source won't find it; obfuscation, not security.
+    script = %{(function(){var i=document.getElementById("#{id}");if(i){i.value="#{digest.reverse}".split("").reverse().join("");}})();}
+
+    @template.hidden_field_tag(:spamtrap_js, '', id: id) +
+      @template.javascript_tag(script, nonce: true)
+  end
 end

data/lib/spamtrap/parameter_filter.rb

@@ -0,0 +1,77 @@
+module Spamtrap
+  # Rails logs params before any before_action runs, so mutated field names reach the log still
+  # encrypted and never match the app's filter_parameters. The Railtie appends BLOCK to
+  # filter_parameters; it decrypts each name and applies the app's own filters to the real one.
+  module ParameterFilter
+    # base64url of IV + at least one name byte + tag, then a date/time select's (Ni) suffix.
+    TOKEN = /\A([A-Za-z0-9_-]{39,})(\(\d+[a-z]\))?\z/
+
+    # Token key => parent paths, built once per params hash; weak so logged params aren't retained.
+    PARENTS = ObjectSpace::WeakMap.new
+
+    # Rails only calls blocks for leaf values no key filter matched, passing a copy of the
+    # value to mutate and the top-level params.
+    BLOCK = lambda do |key, value, params|
+      # Cheapest checks first: this runs for every leaf param of every request Rails filters.
+      next unless Spamtrap.filter_parameters && params.respond_to?(:key?)
+      next unless params.key?('spamtrap_timestamp') || params.key?(:spamtrap_timestamp)
+      next unless value.is_a?(String) && (token = TOKEN.match(key.to_s))
+
+      masked = Spamtrap::ParameterFilter.mask(token, value, params)
+      value.replace(masked) if masked
+    end
+
+    class << self
+      # What the app's filters turn value into at the field's real path, or nil if they leave it.
+      # Only leaf names are mutated, so the containers above the token give the real path. A token
+      # shared by fields_for children has several parents; masking if any path would is the safe side.
+      def mask(token, value, params)
+        filter  = app_filter
+        parents = (PARENTS[params] ||= parent_paths(params)).fetch(token[0], [[]])
+        Spamtrap::Crypto.unverified_field_names(token[1]).each do |name|
+          parents.each do |parent|
+            path   = [*parent, "#{name}#{token[2]}"]
+            result = path.inject(filter.filter(nest(path, value.dup))) { |node, key| node.is_a?(Hash) ? node[key] : node }
+            return result.to_s unless result == value
+          end
+        end
+        nil
+      end
+
+      # The app's filters without BLOCK itself, rebuilt when the list is reassigned or grows.
+      def app_filter
+        filters = Rails.application.config.filter_parameters
+        signature = [filters.object_id, filters.size]
+        return @app_filter if @app_filter_signature == signature
+
+        # Filter before signature, so a concurrent reader never pairs the new signature with the old filter.
+        @app_filter = ActiveSupport::ParameterFilter.new(filters.reject { |f| f.equal?(BLOCK) })
+        @app_filter_signature = signature
+        @app_filter
+      end
+
+      private
+
+      # Array positions are left out of a path, as Rails leaves them out of dotted filter matching.
+      def parent_paths(params)
+        paths = Hash.new { |hash, key| hash[key] = [] }
+        visit = lambda do |node, path|
+          if node.is_a?(Array)
+            node.each { |element| visit.call(element, path) }
+          elsif node.is_a?(Hash)
+            node.each do |key, child|
+              paths[key.to_s] |= [path] if TOKEN.match?(key.to_s)
+              visit.call(child, [*path, key.to_s])
+            end
+          end
+        end
+        visit.call(params, [])
+        paths
+      end
+
+      def nest(path, value)
+        path.reverse.inject(value) { |inner, key| { key => inner } }
+      end
+    end
+  end
+end

data/lib/spamtrap/railtie.rb

@@ -0,0 +1,20 @@
+module Spamtrap
+  class Railtie < Rails::Railtie
+    # on_load so the patches land after app initializers, not at require time.
+    initializer 'spamtrap.install' do
+      ActiveSupport.on_load(:action_controller_base) { Spamtrap.install_controller! }
+      ActiveSupport.on_load(:action_controller_api)  { Spamtrap.install_controller! }
+      ActiveSupport.on_load(:action_view) { Spamtrap.install_form_builder! }
+      # A FormBuilder built before any view renders (e.g. in ActionView::TestCase) would
+      # miss the on_load hook, so patch now if the form helpers are already loaded.
+      Spamtrap.install_form_builder! if Spamtrap.form_builder_loaded?
+    end
+
+    # After the app's initializers, so one that assigns filter_parameters can't drop the block.
+    # Always installed; Spamtrap.filter_parameters switches it at request time.
+    initializer 'spamtrap.filter_parameters', after: :load_config_initializers do |app|
+      filters = app.config.filter_parameters
+      filters << Spamtrap::ParameterFilter::BLOCK unless filters.include?(Spamtrap::ParameterFilter::BLOCK)
+    end
+  end
+end

data/lib/spamtrap/test_helper.rb

@@ -0,0 +1,103 @@
+require 'securerandom'
+require 'spamtrap/crypto'
+require 'spamtrap/controller'
+
+# Not required by lib/spamtrap.rb: apps opt in with `require 'spamtrap/test_helper'`
+# and `include Spamtrap::TestHelper` in their own test cases.
+module Spamtrap
+  module TestHelper
+    # Exposes Crypto's private methods so tests can mint/verify tokens without reimplementing them.
+    class TokenHelper
+      include Spamtrap::Crypto
+      public :spamtrap_encrypt_field, :spamtrap_decrypt_field, :spamtrap_nonce_digest, :spamtrap_js_digest, :spamtrap_aad
+    end
+
+    def spamtrap_token(name, timestamp, context: nil)
+      helper = TokenHelper.new
+      helper.spamtrap_encrypt_field(name.to_s, helper.spamtrap_aad(timestamp, context))
+    end
+
+    def spamtrap_decrypt(token, timestamp, context: nil)
+      helper = TokenHelper.new
+      helper.spamtrap_decrypt_field(token, helper.spamtrap_aad(timestamp, context))
+    end
+
+    # at defaults 5s in the past so Spamtrap.min_fill_time (default 1s) doesn't trap these tokens.
+    def spamtrap_nonce_params(honeypot:, ip:, at: Time.now.to_i - 5, nonce_id: SecureRandom.hex(16), bind_ip: Spamtrap.nonce_bind_ip, context: nil)
+      {
+        spamtrap_timestamp: at,
+        spamtrap_nonce_id:  nonce_id,
+        spamtrap_nonce:     TokenHelper.new.spamtrap_nonce_digest(at, ip, honeypot, nonce_id, bind_ip: bind_ip, context: context)
+      }
+    end
+
+    # The value the inline js_proof script would write into spamtrap_js for a page rendered at `at`.
+    def spamtrap_js_param(honeypot:, at:, context: nil)
+      { spamtrap_js: TokenHelper.new.spamtrap_js_digest(at, honeypot, context: context) }
+    end
+
+    # Builds the params hash an app's own controller test merges into its `post` params:
+    # the honeypot field, plus whatever spamtrap_timestamp/nonce/js_proof fields the declared
+    # options require, so the request clears the whole gauntlet in one call. `fields:` is
+    # merged in as-is, or through spamtrap_mutate first when `mutate:` is truthy.
+    # at defaults 5s in the past so Spamtrap.min_fill_time (default 1s) doesn't trap these tokens.
+    def spamtrap_params(honeypot:, ip: '0.0.0.0', nonce: false, mutate: false, js_proof: false, at: Time.now.to_i - 5, bind_ip: Spamtrap.nonce_bind_ip, fields: nil, context: nil)
+      params = {}
+      if nonce
+        params.merge!(spamtrap_nonce_params(honeypot: honeypot, ip: ip, at: at, bind_ip: bind_ip, context: context))
+      elsif mutate
+        params[:spamtrap_timestamp] = at
+      end
+      if js_proof
+        params[:spamtrap_timestamp] ||= at
+        params.merge!(spamtrap_js_param(honeypot: honeypot, at: at, context: context))
+      end
+      params[honeypot] = ''
+      params.merge!(mutate ? spamtrap_mutate(fields, at: at, context: context) : fields) if fields
+      params
+    end
+
+    # Encrypts every field name in `hash` exactly the way the form builder renders them, so
+    # the result round-trips through spamtrap_remap_hash under a strict action. A key whose
+    # value is a Hash, or an Array of Hashes, is a container (object/fields_for name) and
+    # stays plaintext with its value recursed into; every other key, including one whose
+    # value is an Array of scalars, is a field and gets encrypted as a whole. A trailing
+    # multi-parameter suffix like "(1i)" is preserved after the token. Top-level keys in
+    # FRAMEWORK_PARAMS/CAPTCHA_PARAMS are left alone. Accepts string or symbol keys, returns
+    # string keys.
+    def spamtrap_mutate(hash, at:, context: nil)
+      spamtrap_mutate_hash(hash, at, {}, top_level: true, context: context)
+    end
+
+    private
+
+    # tokens: one token per field name, as the form builder does, so array records stay separate.
+    def spamtrap_mutate_hash(hash, at, tokens, top_level: false, context: nil)
+      allowlist = Spamtrap::Controller::FRAMEWORK_PARAMS + Spamtrap::Controller::CAPTCHA_PARAMS
+
+      hash.each_with_object({}) do |(key, value), memo|
+        key_str = key.to_s
+
+        if top_level && allowlist.include?(key_str)
+          memo[key_str] = value
+        elsif spamtrap_mutate_container?(value)
+          memo[key_str] = spamtrap_mutate_container(value, at, tokens, context: context)
+        else
+          base, suffix = key_str.match(/\A(.+?)(\(\d+[a-z]\))\z/)&.captures
+          name = base || key_str
+          memo["#{tokens[name] ||= spamtrap_token(name, at, context: context)}#{suffix}"] = value
+        end
+      end
+    end
+
+    def spamtrap_mutate_container?(value)
+      value.is_a?(Hash) || (value.is_a?(Array) && value.any? { |el| el.is_a?(Hash) })
+    end
+
+    def spamtrap_mutate_container(value, at, tokens, context: nil)
+      return spamtrap_mutate_hash(value, at, tokens, context: context) if value.is_a?(Hash)
+
+      value.map { |el| el.is_a?(Hash) ? spamtrap_mutate_hash(el, at, tokens, context: context) : el }
+    end
+  end
+end

data/lib/spamtrap/version.rb

@@ -1,5 +1,5 @@
 module Spamtrap
 
-  VERSION = '0.3.5'
+  VERSION = '0.4.3'
 
 end