spamtrap 0.3.4 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1f9fa53d08c869e9952416e63376c31ed74f74584e9cf1e59f7439364c370d5
-  data.tar.gz: 4ecae5a00af343aa3c8856a3f2bcf04999bd37a0112d067d3d907e5b85b75e2a
+  metadata.gz: a31cf3397317c7e4fadc471f44ce713dac53bea0701ba50b24a8259a77ed4b58
+  data.tar.gz: 3c3f3f0119ae22e79a3e327ae5aa1c65b915b906c2bb8b5e3621e536d62ccab2
 SHA512:
-  metadata.gz: 825936fb38cb3095ecf504c42aff353081a8352539a535beff67d85ef2423fc4e7bac328c107d48d5d0ed092ea1b508be6bb06e7490c33cceb2f230a0c89e45a
-  data.tar.gz: c35648761da54aab75b8b8d587f24d4ccfbfb03210d23ed930fbdbea2743876de9a795d19980acac9bac45b92e7bbe94621f8419440031d2e15412b6876e041a
+  metadata.gz: 9abc563f9854fb5759371ac2973b3071b3cc86c4cab3af2566aed9b491079a2870b1df82e1dd5cf561f107a88786a818c42d294678e454cce86522cdabfe4ae0
+  data.tar.gz: 6d4b395ebb6d81a2a002919935001a77a7febdf3353fa5556de2ccd29883ecfe5f29e21b63de448ff53ccfb0233b85708547892cd089123a843775a9aace449d

data/lib/generators/spamtrap/install/install_generator.rb

@@ -0,0 +1,15 @@
+require 'rails/generators'
+
+module Spamtrap
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates a Spamtrap initializer documenting every configuration option and its default.'
+
+      def create_initializer
+        template 'spamtrap.rb', 'config/initializers/spamtrap.rb'
+      end
+    end
+  end
+end

data/lib/generators/spamtrap/install/templates/spamtrap.rb

@@ -0,0 +1,75 @@
+# Spamtrap global configuration. Every option can be overridden per controller action or
+# per render; an explicit value there always wins, including `false` over a global `true`.
+# See https://github.com/cedric/spamtrap/ for the full guide.
+
+# Honeypot
+
+# Decoys f.spamtrap renders: any of :textarea, :text, :checkbox.
+# Spamtrap.honeypot_styles = [:textarea]
+
+# Require a hidden field that only an executing script fills in; excludes no-JS users.
+# Spamtrap.js_proof = false
+
+# Nonce
+
+# false, true, or :single_use.
+# Spamtrap.nonce = false
+
+# Seconds; also caps mutation token age unless mutation_timeout is set.
+# Spamtrap.nonce_timeout = 1800
+
+# Seconds a submitted timestamp may sit in the future.
+# Spamtrap.nonce_skew = 60
+
+# true (full IP), :prefix (/24 IPv4 or /48 IPv6), or false (not bound).
+# Spamtrap.nonce_bind_ip = true
+
+# Where nonce: :single_use records seen nonce ids; defaults to the app's cache.
+# Spamtrap.nonce_store = Rails.cache
+
+# Mutation
+
+# false, true/:strict (traps plaintext keys), or :lenient (remap only).
+# Spamtrap.mutate = false
+
+# Seconds; defaults to nonce_timeout.
+# Spamtrap.mutation_timeout = nil
+
+# Extra top-level param names a strict action accepts unencrypted.
+# Spamtrap.allowed_params = []
+
+# Whether mutated fields keep an id/for derived from the real field name.
+# Spamtrap.stable_ids = true
+
+# Fill time
+
+# Minimum seconds between render and submission a human needs; false or 0 disables.
+# Spamtrap.min_fill_time = 1
+
+# Responses and callbacks
+
+# How a trapped request responds: :head, :no_content, :unprocessable, :redirect_back,
+# a callable, or a Hash keyed by trap reason.
+# Spamtrap.trap_response = :head
+
+# Optional callback invoked whenever the spamtrap fires.
+# Spamtrap.on_trap = ->(reason:, request:) { }
+
+# App-defined heuristic run after every other check; truthy result traps as :content.
+# Spamtrap.suspicious_if = nil
+
+# Keys
+
+# The current HKDF source secret; defaults to the app's own so no setup is needed to opt in.
+# Spamtrap.secret_key_base = nil
+
+# Set during a rotation window so tokens minted under the old secret still verify/decrypt.
+# Spamtrap.previous_secret_key_base = nil
+
+# Binds tokens to a value derived from the request (e.g. host), for multi-tenant apps; off by default.
+# Spamtrap.token_context = nil
+
+# Testing
+
+# Global kill switch; false skips every spamtrap check. Handy for test environments.
+# Spamtrap.enabled = true

data/lib/spamtrap/controller.rb

@@ -1,6 +1,16 @@
 module Spamtrap::Controller
   include Spamtrap::Crypto
 
+  # Fields Rails/browsers/forms add that a strict action must not treat as attacker-controlled plaintext.
+  FRAMEWORK_PARAMS = %w[
+    authenticity_token commit button _method utf8
+    spamtrap_timestamp spamtrap_nonce spamtrap_nonce_id spamtrap_js
+  ].freeze
+
+  # Captcha widgets inject their own plaintext param the app can't encrypt: Google
+  # reCAPTCHA v2/v3, hCaptcha, and Cloudflare Turnstile.
+  CAPTCHA_PARAMS = %w[g-recaptcha-response h-captcha-response cf-turnstile-response].freeze
+
   def self.included(base)
     base.extend ActsAsMethods
   end
@@ -9,79 +19,263 @@ module Spamtrap::Controller
     def spamtrap(honeypot = 'spamtrap', options = {}, &block)
       # Capture explicit per-call values; use sentinel so globals are read
       # at request time rather than at class definition time.
-      nonce_opt    = options.key?(:nonce)         ? options.delete(:nonce)         : :global
-      timeout_opt  = options.key?(:nonce_timeout) ? options.delete(:nonce_timeout) : :global
-      mutate_opt   = options.key?(:mutate)        ? options.delete(:mutate)        : :global
-      on_trap_opt  = options.key?(:on_trap)       ? options.delete(:on_trap)       : :global
+      nonce_opt         = options.key?(:nonce)         ? options.delete(:nonce)         : :global
+      timeout_opt       = options.key?(:nonce_timeout) ? options.delete(:nonce_timeout) : :global
+      mutate_opt        = options.key?(:mutate)        ? options.delete(:mutate)        : :global
+      on_trap_opt       = options.key?(:on_trap)       ? options.delete(:on_trap)       : :global
+      trap_response_opt = options.key?(:trap_response) ? options.delete(:trap_response) : :global
+      nonce_bind_ip_opt = options.key?(:nonce_bind_ip) ? options.delete(:nonce_bind_ip) : :global
+      min_fill_time_opt = options.key?(:min_fill_time) ? options.delete(:min_fill_time) : :global
+      js_proof_opt      = options.key?(:js_proof)      ? options.delete(:js_proof)      : :global
+      suspicious_if_opt = options.key?(:suspicious_if) ? options.delete(:suspicious_if) : :global
 
       before_action(options) do |controller|
+        next unless Spamtrap.enabled
+
         controller.instance_eval(&block) if block_given?
         controller.instance_eval do
-          nonce_enabled  = nonce_opt   == :global ? Spamtrap.nonce         : nonce_opt
-          nonce_timeout  = timeout_opt == :global ? Spamtrap.nonce_timeout : timeout_opt
-          mutate_enabled = mutate_opt  == :global ? Spamtrap.mutate        : mutate_opt
-
-          spamtrap_remap_params if mutate_enabled
-
-          if params[honeypot].present?
-            Rails.logger.warn "Spamtrap triggered by #{request.remote_ip}."
-            spamtrap_invoke_on_trap(:honeypot, on_trap_opt)
-            head 200
-          elsif nonce_enabled && !spamtrap_valid_nonce?(nonce_timeout)
-            Rails.logger.warn "Spamtrap nonce invalid from #{request.remote_ip}."
-            spamtrap_invoke_on_trap(:nonce, on_trap_opt)
-            head 200
+          nonce_enabled     = nonce_opt         == :global ? Spamtrap.nonce         : nonce_opt
+          nonce_timeout     = timeout_opt       == :global ? Spamtrap.nonce_timeout : timeout_opt
+          mutate_enabled    = mutate_opt        == :global ? Spamtrap.mutate        : mutate_opt
+          bind_ip           = nonce_bind_ip_opt == :global ? Spamtrap.nonce_bind_ip : nonce_bind_ip_opt
+          min_fill_time     = min_fill_time_opt == :global ? Spamtrap.min_fill_time : min_fill_time_opt
+          js_proof_enabled  = js_proof_opt      == :global ? Spamtrap.js_proof      : js_proof_opt
+          suspicious_hook   = suspicious_if_opt == :global ? Spamtrap.suspicious_if : suspicious_if_opt
+          # true and :strict both trap plaintext keys; :lenient only remaps.
+          strict            = mutate_enabled && mutate_enabled != :lenient
+          context           = Spamtrap.token_context_for(request)
+
+          remap = spamtrap_remap_params(Spamtrap.mutation_timeout, context) if mutate_enabled
+
+          if Spamtrap.honeypot_fields(honeypot).each_value.any? { |field| params[field].present? }
+            spamtrap_trap(:honeypot, honeypot, on_trap_opt, trap_response_opt)
+          # :expired traps in lenient mode too, or a remapped-but-stale token would otherwise be accepted.
+          elsif mutate_enabled && remap[0] == :expired
+            spamtrap_trap(:mutation_expired, honeypot, on_trap_opt, trap_response_opt)
+          elsif strict && (reason = spamtrap_strict_violation(remap, honeypot))
+            spamtrap_trap(reason, honeypot, on_trap_opt, trap_response_opt)
+          elsif nonce_enabled && (reason = spamtrap_nonce_failure(nonce_timeout, honeypot, nonce_enabled, bind_ip: bind_ip, min_fill_time: min_fill_time, context: context))
+            spamtrap_trap(reason, honeypot, on_trap_opt, trap_response_opt)
+          # Mutation-only forms: the nonce path above already applied the fill time.
+          elsif !nonce_enabled && mutate_enabled && spamtrap_too_fast?(min_fill_time)
+            spamtrap_trap(:too_fast, honeypot, on_trap_opt, trap_response_opt)
+          elsif js_proof_enabled && (reason = spamtrap_js_proof_failure(honeypot, context: context))
+            spamtrap_trap(reason, honeypot, on_trap_opt, trap_response_opt)
+          elsif suspicious_hook && spamtrap_content_suspicious?(suspicious_hook)
+            spamtrap_trap(:content, honeypot, on_trap_opt, trap_response_opt)
           end
         end
       end
     end
   end
 
-  def spamtrap_valid_nonce?(timeout)
+  def spamtrap_nonce_failure(timeout, honeypot, mode, bind_ip: Spamtrap.nonce_bind_ip, min_fill_time: Spamtrap.min_fill_time, context: nil)
     timestamp = params[:spamtrap_timestamp].to_i
-    nonce = params[:spamtrap_nonce].to_s
-    return false if timestamp.zero? || nonce.empty?
-    return false if Time.now.to_i - timestamp > timeout.to_i
+    nonce     = params[:spamtrap_nonce].to_s
+    nonce_id  = params[:spamtrap_nonce_id].to_s
+    return :nonce_missing if timestamp.zero? || nonce.blank? || nonce_id.blank?
 
-    secret = Rails.application.secret_key_base
-    expected = OpenSSL::HMAC.hexdigest('SHA256', secret, "#{timestamp}:#{request.remote_ip}")
-    ActiveSupport::SecurityUtils.secure_compare(nonce, expected)
-  end
+    now = Time.now.to_i
+    # nonce_id doubles as a cache key under single-use mode, so bound its shape.
+    return :nonce_invalid unless nonce_id.match?(/\A[0-9a-f]{32}\z/)
+    return :nonce_invalid if timestamp - now > Spamtrap.nonce_skew
+    return :nonce_expired if now - timestamp > timeout.to_i # checked before the HMAC so a genuine expired token reports as expired
 
-  def spamtrap_remap_params
-    salt_hex = params[:spamtrap_mutation_salt].to_s
-    return if salt_hex.empty?
+    expected = spamtrap_nonce_digest(timestamp, request.remote_ip, honeypot, nonce_id, bind_ip: bind_ip, context: context)
+    unless ActiveSupport::SecurityUtils.secure_compare(nonce, expected)
+      # Retry with the previous secret during a rotation window before giving up.
+      previous_secret = Spamtrap.previous_secret_key_base
+      previous = previous_secret && spamtrap_nonce_digest(timestamp, request.remote_ip, honeypot, nonce_id, bind_ip: bind_ip, secret: previous_secret, context: context)
+      return :nonce_invalid unless previous && ActiveSupport::SecurityUtils.secure_compare(nonce, previous)
+    end
 
-    salt_bytes = [salt_hex].pack('H*')
-    return unless salt_bytes.bytesize == Spamtrap::Crypto::NONCE_LEN
+    # After the HMAC (so a forged timestamp is :nonce_invalid) but before single-use records
+    # the id, or a human trapped as too fast could never resubmit the same page.
+    return :too_fast if spamtrap_too_fast?(min_fill_time)
+
+    if mode == :single_use
+      key    = "spamtrap:nonce:#{nonce_id}"
+      stored = Spamtrap.nonce_store.write(key, 1, unless_exist: true, expires_in: timeout.to_i + Spamtrap.nonce_skew)
+      if Spamtrap.nonce_store.is_a?(ActiveSupport::Cache::NullStore)
+        Spamtrap::Controller.warn_null_store_once
+      elsif !stored
+        return :nonce_replayed
+      end
+    end
 
-    spamtrap_remap_hash(params, salt_bytes)
-  rescue ArgumentError
     nil
   end
 
-  def spamtrap_remap_hash(hash, salt)
+  # Warned once per process: a NullStore accepts every write, so it can never catch a replay.
+  def self.warn_null_store_once
+    return if @null_store_warned
+    @null_store_warned = true
+    Rails.logger.warn 'Spamtrap: nonce: :single_use needs a real Spamtrap.nonce_store; NullStore cannot detect replays.'
+  end
+
+  def spamtrap_too_fast?(min_fill_time)
+    return false unless min_fill_time && min_fill_time.to_i.positive?
+
+    ts = params[:spamtrap_timestamp].to_i
+    ts.positive? && Time.now.to_i - ts < min_fill_time.to_i
+  end
+
+  # Returns [:missing, []], [:expired, leftovers], or [:ok, leftovers], where leftovers is
+  # an array of [key, depth] for every submitted key that did not decrypt (depth 0 == top
+  # level of params), letting spamtrap_strict_violation tell :missing apart from a real
+  # plaintext violation. :expired still remaps every key (no additional staleness bound on
+  # the decrypt itself) so on_trap/trap_response can re-render the form with the user's
+  # input; the action never runs, so an old token can only help show that input back, and
+  # key rotation bounds how far back it can reach.
+  def spamtrap_remap_params(timeout, context = nil)
+    ts = params[:spamtrap_timestamp].to_i
+    return [:missing, []] if ts.zero?
+
+    now = Time.now.to_i
+    status = now - ts > timeout.to_i || ts - now > Spamtrap.nonce_skew ? :expired : :ok
+    [status, spamtrap_remap_hash(params, spamtrap_aad(ts, context))]
+  end
+
+  def spamtrap_remap_hash(hash, aad, depth = 0)
+    leftovers = []
     hash.each_key.to_a.each do |key|
-      real = spamtrap_decrypt_field(key.to_s, salt)
+      key_str = key.to_s
+      # Rails date/time selects post <token>(1i)/(2i)/(3i); decrypt the base, keep the suffix.
+      base, suffix = key_str.match(/\A(.+?)(\(\d+[a-z]\))\z/)&.captures
+      real = spamtrap_decrypt_field(base || key_str, aad)
       if real
-        hash[real] = hash.delete(key)
-        key = real
+        renamed = suffix ? "#{real}#{suffix}" : real
+        hash[renamed] = hash.delete(key)
+        key = renamed
       end
       child = hash[key]
-      spamtrap_remap_hash(child, salt) if child.is_a?(ActionController::Parameters)
+      # A nesting container (object name, or array of them) is structure, not a submitted
+      # field name, so it's never itself flagged even when its own key didn't decrypt.
+      container = child.is_a?(ActionController::Parameters) ||
+                  (child.is_a?(Array) && child.any? { |el| el.is_a?(ActionController::Parameters) })
+      leftovers << [key.to_s, depth] if real.nil? && !container
+      case child
+      when ActionController::Parameters
+        leftovers.concat(spamtrap_remap_hash(child, aad, depth + 1))
+      when Array
+        child.each { |el| leftovers.concat(spamtrap_remap_hash(el, aad, depth + 1)) if el.is_a?(ActionController::Parameters) }
+      end
     end
+    leftovers
+  end
+
+  # nil means no violation. :mutation_expired means no timestamp was submitted at all, so
+  # blaming a specific field with :plaintext_field would mislead (the :expired case is
+  # already handled by the caller before this runs). Otherwise: any leftover below the top
+  # level always traps (plaintext smuggled into an otherwise-encrypted nested object); a
+  # top-level leftover only traps if it isn't allowlisted.
+  def spamtrap_strict_violation(remap, honeypot)
+    status, leftovers = remap
+    return :mutation_expired if status == :missing
+    return :plaintext_field if leftovers.any? { |_key, depth| depth > 0 }
+
+    # controller/action/id/format are Rails' own routing params, always present and always plaintext.
+    allowed = FRAMEWORK_PARAMS + CAPTCHA_PARAMS + Spamtrap.honeypot_fields(honeypot).values +
+              request.path_parameters.keys.map(&:to_s) + Spamtrap.allowed_params
+    :plaintext_field if leftovers.any? { |key, _depth| !allowed.include?(key) }
   end
 
-  def spamtrap_invoke_on_trap(reason, on_trap_opt)
+  # ts.zero? means no timestamp was submitted at all, so there's nothing to bind spamtrap_js to.
+  # The token is public in the page source, so without nonce or mutation the timestamp is the
+  # only thing that expires it; bound its age like a nonce.
+  def spamtrap_js_proof_failure(honeypot, context: nil)
+    ts = params[:spamtrap_timestamp].to_i
+    js = params[:spamtrap_js].to_s
+    return :no_js if ts.zero? || js.blank?
+
+    now = Time.now.to_i
+    return :no_js if now - ts > Spamtrap.nonce_timeout.to_i || ts - now > Spamtrap.nonce_skew
+
+    expected = spamtrap_js_digest(ts, honeypot, context: context)
+    return nil if ActiveSupport::SecurityUtils.secure_compare(js, expected)
+
+    # Retry with the previous secret during a rotation window before giving up.
+    previous_secret = Spamtrap.previous_secret_key_base
+    previous = previous_secret && spamtrap_js_digest(ts, honeypot, secret: previous_secret, context: context)
+    return nil if previous && ActiveSupport::SecurityUtils.secure_compare(js, previous)
+
+    :no_js
+  end
+
+  # A raising hook is treated as not suspicious (fail open); a bug in an app's own
+  # keyword regex must not end up trapping every visitor.
+  def spamtrap_content_suspicious?(callable)
+    !!spamtrap_call(callable, { params: params, request: request, controller: self }, positional: params)
+  rescue StandardError => e
+    Rails.logger.error "Spamtrap suspicious_if callback raised: #{e.class}: #{e.message}"
+    false
+  end
+
+  # Logs, invokes on_trap, then applies the trap response unless the callback already
+  # rendered/redirected (performed? short-circuits so a custom on_trap response wins).
+  def spamtrap_trap(reason, honeypot, on_trap_opt, trap_response_opt)
+    Rails.logger.warn "Spamtrap #{reason} from #{request.remote_ip}."
+    payload = { reason: reason, honeypot: honeypot.to_s, controller: controller_path, action: action_name, ip: request.remote_ip, request: request }
+    ActiveSupport::Notifications.instrument('trap.spamtrap', payload) { }
+    spamtrap_invoke_on_trap(reason, on_trap_opt, honeypot)
+    return if performed?
+
+    setting = trap_response_opt == :global ? Spamtrap.trap_response : trap_response_opt
+    spamtrap_render_trap(reason, setting)
+  end
+
+  # setting: a Hash keyed by reason (falls back to :default, then :head), a callable
+  # (controller, reason), or one of :head/:no_content/:unprocessable/:redirect_back.
+  def spamtrap_render_trap(reason, setting)
+    if setting.is_a?(Hash)
+      spamtrap_render_trap(reason, setting[reason] || setting[:default] || :head)
+    elsif setting.respond_to?(:call)
+      setting.call(self, reason)
+      head 200 unless performed? # callable didn't render/redirect, so fall back
+    elsif setting == :head
+      head 200
+    elsif setting == :no_content
+      head 204
+    elsif setting == :unprocessable
+      head 422
+    elsif setting == :redirect_back
+      redirect_back_or_to('/', status: :see_other)
+    else
+      raise ArgumentError, "Unknown Spamtrap.trap_response: #{setting.inspect}"
+    end
+  end
+
+  def spamtrap_invoke_on_trap(reason, on_trap_opt, honeypot)
     callback = on_trap_opt == :global ? Spamtrap.on_trap : on_trap_opt
     return unless callback.respond_to?(:call)
-    callback.call(reason: reason, request: request)
+
+    payload = { reason: reason, request: request, controller: self, honeypot: honeypot.to_s, params: params }
+    spamtrap_call(callback, payload, positional: payload)
   rescue StandardError => e
     Rails.logger.error "Spamtrap on_trap callback raised: #{e.class}: #{e.message}"
   end
 
-  private :spamtrap_valid_nonce?, :spamtrap_remap_params, :spamtrap_remap_hash, :spamtrap_invoke_on_trap
+  # Dispatches a user-supplied callable per its declared parameters, shared by on_trap and
+  # suspicious_if: kwrest gets the whole payload, keywords get a matching slice, a bare
+  # positional gets `positional` (the payload for on_trap, params for suspicious_if).
+  def spamtrap_call(callable, payload, positional:)
+    # Procs report :parameters directly; other callables (methods, etc.) need it via #method(:call).
+    parameters = callable.respond_to?(:parameters) ? callable.parameters : callable.method(:call).parameters
 
-end
+    if parameters.any? { |type, _| type == :keyrest }
+      callable.call(**payload)
+    elsif parameters.any? { |type, _| type == :key || type == :keyreq }
+      names = parameters.select { |type, _| type == :key || type == :keyreq }.map { |_, name| name }
+      callable.call(**payload.slice(*names))
+    elsif parameters.any? { |type, _| type == :req || type == :opt || type == :rest }
+      callable.call(positional)
+    else
+      callable.call
+    end
+  end
 
-ActionController::Base.send :include, Spamtrap::Controller
+  private :spamtrap_nonce_failure, :spamtrap_too_fast?, :spamtrap_remap_params, :spamtrap_remap_hash,
+          :spamtrap_strict_violation, :spamtrap_trap, :spamtrap_render_trap, :spamtrap_invoke_on_trap,
+          :spamtrap_call, :spamtrap_js_proof_failure, :spamtrap_content_suspicious?
+
+end

data/lib/spamtrap/crypto.rb

@@ -1,4 +1,6 @@
 require 'base64'
+require 'securerandom'
+require 'ipaddr'
 
 module Spamtrap
   module Crypto
@@ -7,40 +9,87 @@ module Spamtrap
     NONCE_LEN = 12
     TAG_LEN   = 16
 
+    class << self
+      # HKDF-derives {mutation:, nonce:} keys, memoised per secret at module level so each
+      # request doesn't re-derive them; previous_secret_key_base is what keeps a rotation from
+      # orphaning in-flight forms.
+      def keys_for(secret)
+        @keys_cache ||= {}
+        @keys_cache[secret] ||= begin
+          derived = {
+            mutation: OpenSSL::KDF.hkdf(secret, salt: 'spamtrap-mutation', info: '', length: KEY_LEN, hash: 'SHA256'),
+            nonce:    OpenSSL::KDF.hkdf(secret, salt: 'spamtrap-nonce',    info: '', length: 32,       hash: 'SHA256')
+          }
+          # Cap at the two most recent secrets so a test suite rotating secrets can't grow this unboundedly.
+          @keys_cache.delete(@keys_cache.keys.first) while @keys_cache.size > 1
+          derived
+        end
+      end
+    end
+
     private
 
-    def spamtrap_crypto_key
-      @spamtrap_crypto_key ||= OpenSSL::KDF.hkdf(
-        Rails.application.secret_key_base,
-        salt:   'spamtrap-mutation',
-        info:   '',
-        length: KEY_LEN,
-        hash:   'SHA256'
-      )
+    # Appended only when context is non-nil, so the default AAD/message shape is unchanged.
+    def spamtrap_aad(timestamp, context)
+      context.nil? ? timestamp.to_s : "#{timestamp}:#{context}"
     end
 
-    def spamtrap_encrypt_field(field_name, salt_bytes)
+    # aad binds the token to the render timestamp so it can't be replayed under a different one.
+    def spamtrap_encrypt_field(field_name, aad)
       cipher = OpenSSL::Cipher.new(CIPHER)
       cipher.encrypt
-      cipher.key = spamtrap_crypto_key
-      cipher.iv  = salt_bytes
+      cipher.key = Spamtrap::Crypto.keys_for(Spamtrap.secret_key_base)[:mutation]
+      cipher.iv  = iv = SecureRandom.bytes(NONCE_LEN)
+      cipher.auth_data = aad.to_s
       ct = cipher.update(field_name.to_s) + cipher.final
-      Base64.urlsafe_encode64(ct + cipher.auth_tag(TAG_LEN), padding: false)
+      Base64.urlsafe_encode64(iv + ct + cipher.auth_tag(TAG_LEN), padding: false)
     end
 
-    def spamtrap_decrypt_field(token, salt_bytes)
+    # Tries the current secret, then the previous one (rotation window), before giving up.
+    def spamtrap_decrypt_field(token, aad)
       raw = Base64.urlsafe_decode64(token)
-      return nil if raw.bytesize <= TAG_LEN
-      ct  = raw[0, raw.bytesize - TAG_LEN]
+      return nil unless raw.bytesize > NONCE_LEN + TAG_LEN
+
+      [Spamtrap.secret_key_base, Spamtrap.previous_secret_key_base].compact.each do |secret|
+        result = spamtrap_decrypt_raw(raw, aad, secret)
+        return result if result
+      end
+      nil
+    rescue ArgumentError
+      nil
+    end
+
+    def spamtrap_decrypt_raw(raw, aad, secret)
+      iv  = raw[0, NONCE_LEN]
+      ct  = raw[NONCE_LEN...-TAG_LEN]
       tag = raw[-TAG_LEN..]
       cipher = OpenSSL::Cipher.new(CIPHER)
       cipher.decrypt
-      cipher.key      = spamtrap_crypto_key
-      cipher.iv       = salt_bytes
-      cipher.auth_tag = tag
+      cipher.key       = Spamtrap::Crypto.keys_for(secret)[:mutation]
+      cipher.iv        = iv
+      cipher.auth_data = aad.to_s
+      cipher.auth_tag  = tag
       (cipher.update(ct) + cipher.final).to_sym
-    rescue OpenSSL::Cipher::CipherError, ArgumentError
+    rescue OpenSSL::Cipher::CipherError
       nil
     end
+
+    # Value the inline script writes into spamtrap_js. Visible in the page source by design:
+    # it proves a script ran, not that the client is honest.
+    def spamtrap_js_digest(timestamp, honeypot, secret: Spamtrap.secret_key_base, context: nil)
+      key = Spamtrap::Crypto.keys_for(secret)[:nonce]
+      message = "js:v1:#{timestamp}:#{honeypot}"
+      message += ":#{context}" unless context.nil? # appended only when present so the default digest is unchanged
+      OpenSSL::HMAC.hexdigest('SHA256', key, message)
+    end
+
+    # v1: versions the message for future key rotation; honeypot scopes a token to one form.
+    # secret defaults to current but the caller retries with previous_secret_key_base on mismatch.
+    def spamtrap_nonce_digest(timestamp, ip, honeypot, nonce_id, bind_ip: Spamtrap.nonce_bind_ip, secret: Spamtrap.secret_key_base, context: nil)
+      key = Spamtrap::Crypto.keys_for(secret)[:nonce]
+      message = "v1:#{timestamp}:#{Spamtrap.normalize_ip(ip, bind_ip)}:#{honeypot}:#{nonce_id}"
+      message += ":#{context}" unless context.nil? # appended only when present so the default digest is unchanged
+      OpenSSL::HMAC.hexdigest('SHA256', key, message)
+    end
   end
 end