permittable 0.10.0 → 0.11.1

data/lib/permittable.rb

@@ -136,7 +136,8 @@ require "permittable/filter_parameter_registry"
 # declaring `transform:`: its default is stored exactly AS AUTHORED, never
 # cast — `transform:` never runs on a default either (see OUTPUT RESHAPING),
 # so author such a default already in the shape the action should receive.
-# Either way it is deep-frozen on a copy, and each request gets its own deep
+# An `example:` is cast either way and never transformed: it documents what a
+# client sends. Either way it is deep-frozen on a copy, and each request gets its own deep
 # copy, so no request can corrupt it for the next.
 #
 # `nullable: true` splits that rule in two for one field, which is how a PATCH
@@ -218,18 +219,29 @@ module Permittable
   UNKNOWN_MODES = %i[ignore log error].freeze
   MODES = %i[enforce monitor].freeze
   ERROR_FORMATS = %i[envelope problem].freeze
+  # A Permittable.audit_ignore entry: a controller path the way Rails names
+  # it (lowercase, `/`-separated — "active_storage/direct_uploads"),
+  # optionally followed by "#action".
+  AUDIT_IGNORE_ENTRY = %r{\A[a-z0-9_]+(?:/[a-z0-9_]+)*(?:#\w+)?\z}
   # Rails merges routing bookkeeping into params; a top-level (root: false)
   # unknown-keys check must not flag them.
   ROUTING_KEYS = %w[controller action format].freeze
   # Nor the keys an ordinary form POST carries — the CSRF token, the verb
-  # override, the encoding probe, and the submit button's name. Without this
-  # `unknown: :error` was unusable outside a JSON API: every browser form
-  # failed on the framework's own keys rather than on anything the client got
-  # wrong. Exempt from the CHECK only: unlike the routing keys these are NOT
-  # stripped from monitor mode's raw pass-through, where handing back an
-  # untouched params hash is the whole promise and a legacy action may well
-  # read `_method` itself.
-  FORM_KEYS = %w[authenticity_token _method utf8 commit].freeze
+  # override, the encoding probe, and the submit button's name: `commit` from
+  # f.submit/submit_tag, `button` from f.button/button_tag (which render
+  # <button name="button">, so a browser sends `button=` even with no
+  # value). Without this `unknown: :error` was unusable outside a JSON API:
+  # every browser form failed on the framework's own keys rather than on
+  # anything the client got wrong. Exempt from the CHECK only: unlike the
+  # routing keys these are NOT stripped from monitor mode's raw
+  # pass-through, where handing back an untouched params hash is the whole
+  # promise and a legacy action may well read `_method` itself.
+  #
+  # The click point of an image submit (image_submit_tag, which has no name
+  # of its own to exempt) is a form key too, but not a fixed one: `x` and `y`,
+  # or `<name>.x` and `<name>.y`, as a PAIR of digits. See
+  # permittable_image_submit_keys.
+  FORM_KEYS = %w[authenticity_token _method utf8 commit button].freeze
   # ROUTING_KEYS/FORM_KEYS name where the keys come FROM; these two name what
   # is DECIDED with them, which is what the call sites care about — and the
   # asymmetry between them is the deliberate point, so spell it once here
@@ -238,7 +250,7 @@ module Permittable
   MONITOR_DROPPED_KEYS = ROUTING_KEYS
   # The field kinds that can hold ParamsWrapper's copy of a body — a hash. A
   # rootless contract declaring the wrapper key as one of these reads the
-  # copy deliberately, so it is kept (see permittable_without_wrapper_copy).
+  # copy deliberately, so it is kept (see permittable_drops_wrapper_copy?).
   WRAPPER_CONTAINER_KINDS = [:nested, JSON_TYPE].freeze
   # A log line and an exception message are PROSE, written for a person. They
   # list at most this many names and count the rest, so one request cannot
@@ -512,6 +524,55 @@ module Permittable
       @check_column_types = value
     end
 
+    # Routed actions that `permittable:audit` leaves out of its counts and of
+    # `[strict]`, and that `permittable:generate` does not draft for — the
+    # endpoints that are not the app's to guard:
+    #
+    #   Permittable.audit_ignore = %w[active_storage/direct_uploads application#not_found]
+    #
+    # Each entry is a controller path as Rails routes it (every action of that
+    # controller) or "controller#action" (that one action, on every verb — a
+    # `via: :all` catch-all is one entry). Ignored actions are still listed,
+    # in a section of their own, and an entry that matches no routed action is
+    # listed too: an ignore list nothing checks would hide its own typos.
+    #
+    # Strings only, checked here. A class name is the likeliest mistake and
+    # the error names the path meant; a Class is refused because naming one
+    # in an initializer autoloads it at boot, which Zeitwerk refuses for a
+    # reloadable controller; a Regexp is refused because a pattern would also
+    # ignore controllers written AFTER it, and catching a new unguarded
+    # endpoint is what the gate is for. Validated as a whole before anything
+    # is stored, so a rejected list leaves the previous one in place. nil
+    # clears it.
+    def audit_ignore
+      @audit_ignore || [].freeze
+    end
+
+    def audit_ignore=(entries)
+      entries = Array(entries).map { |entry| audit_ignore_entry(entry) }
+      @audit_ignore = entries.uniq.freeze
+    end
+
+    # Whether the audit and the generator also leave out every controller
+    # whose source is outside Rails.root — engines and gems: ActiveStorage,
+    # ActionMailbox, Rails's own rails/* controllers. On by default, since an
+    # app cannot add a contract to a gem's controller; those are listed in
+    # the report under their own reason rather than dropped. Turn it off to
+    # audit them like the app's own:
+    #
+    #   Permittable.audit_ignore_outside_root = false
+    #
+    # See Audit.outside_root? for how a controller is located.
+    def audit_ignore_outside_root
+      @audit_ignore_outside_root.nil? || @audit_ignore_outside_root
+    end
+
+    def audit_ignore_outside_root=(value)
+      raise ArgumentError, "#{LABEL}: audit_ignore_outside_root must be true or false" unless [true, false].include?(value)
+
+      @audit_ignore_outside_root = value
+    end
+
     # App-wide fallback copy for a violation code, looked up through I18n
     # under permittable.errors.<code> ("missing", "inclusion", or any Symbol
     # a validate: returned). Consulted only when the field declares no
@@ -526,6 +587,24 @@ module Permittable
       message = ::I18n.t("permittable.errors.#{code}", default: nil)
       message.is_a?(String) ? message : nil
     end
+
+    private
+
+    # One audit_ignore entry, frozen, or an ArgumentError that says what an
+    # entry looks like — and, for a class or a class name, which path it
+    # meant: `ActiveStorage::DirectUploadsController` is the path
+    # "active_storage/direct_uploads", the same derivation Rails's own
+    # controller_path makes.
+    def audit_ignore_entry(entry)
+      return entry.dup.freeze if entry.is_a?(String) && AUDIT_IGNORE_ENTRY.match?(entry)
+
+      meant = entry.controller_path if entry.is_a?(Class) && entry.respond_to?(:controller_path)
+      meant ||= entry.underscore.delete_suffix("_controller") if entry.is_a?(String) && entry.match?(/\A[A-Z]\w*(::[A-Z]\w*)*\z/)
+      raise ArgumentError,
+            "#{LABEL}: audit_ignore takes controller paths as Rails routes them (\"active_storage/direct_uploads\") " \
+            "or \"controller#action\" (\"application#not_found\"), got #{entry.inspect}" \
+            "#{" — did you mean #{meant.inspect}?" if meant}"
+    end
   end
 
   # Raised when the request violates the matching contract. `details` is an
@@ -545,6 +624,12 @@ module Permittable
     class_attribute :permittable_contracts, instance_accessor: false, default: []
 
     rescue_from InvalidParameters, with: :render_invalid_parameters if respond_to?(:rescue_from)
+    # Registered here, at the include, and not at the first `permit_params`:
+    # the README documents `skip_before_action :enforce_params_contract`, and
+    # Rails raises when it is asked to skip a callback that is not defined
+    # yet. The cost is the order: this check runs before any callback
+    # declared after the include (see the README's "Per-request locales"),
+    # so a locale switch that must cover it is a `prepend_around_action`.
     before_action :enforce_params_contract if respond_to?(:before_action)
   end
 
@@ -808,8 +893,11 @@ module Permittable
       source.split(/[eE]/, 2).first.match?(/[1-9]/)
     end
 
+    # Rational#to_s is "1/2", which BigDecimal() cannot read, so the generic
+    # Numeric branch refused every Rational, even a whole one (3r).
     def cast_decimal(value)
       case value
+      when Rational then rational_to_decimal(value)
       when Numeric then finite_decimal(BigDecimal(value.to_s))
       when String then value.match?(NUMERIC_FORMAT) ? finite_decimal(BigDecimal(value)) : [:error, "invalid_type"]
       else [:error, "invalid_type"]
@@ -818,6 +906,20 @@ module Permittable
       [:error, "invalid_type"]
     end
 
+    # A Rational is exactly a decimal only when its reduced denominator has
+    # no prime factor but 2 and 5 (1/2, 3/40), and then it divides 10**k for
+    # k = its bit length, which is at least the exponent of either factor.
+    # Anything else (1/3) has no finite expansion, so a BigDecimal could hold
+    # it only rounded at a precision this gem would have to pick. That is the
+    # guess every other coercion here refuses, so it is invalid_type.
+    def rational_to_decimal(value)
+      denominator = value.denominator
+      scale = denominator.bit_length
+      return [:error, "invalid_type"] unless ((10**scale) % denominator).zero?
+
+      finite_decimal(BigDecimal("#{value.numerator * (10**scale) / denominator}e-#{scale}"))
+    end
+
     # BigDecimal has no exponent limit, so a :decimal cannot overflow — but
     # BigDecimal("NaN") and BigDecimal("Infinity") SUCCEED where Float()
     # raises, so a client could send the literal string "NaN" for a price and
@@ -1128,6 +1230,7 @@ module Permittable
       validate_array_authored_value!(field, :default) if field.key?(:default)
       validate_array_authored_value!(field, :example) if field.key?(:example)
       validate_message!(field)
+      freeze_desc!(field)
       @fields << field
     end
 
@@ -1204,6 +1307,7 @@ module Permittable
                   fields: nested_fields!(name, &block), **opts }
         field[:fields] = cascade_sensitive(field[:fields], field[:sensitive])
         validate_message!(field)
+        freeze_desc!(field)
       elsif type&.to_sym == JSON_TYPE
         assert_opts!(name, opts, JSON_OPTS)
         # `type:` is carried alongside `kind:` so the same `as(:json)` matcher
@@ -1308,6 +1412,7 @@ module Permittable
       validate_authored_value!(field, :default)
       validate_authored_value!(field, :example)
       validate_message!(field)
+      freeze_desc!(field)
     end
 
     # `in:` is a Range (bounds-checked with cover?), a list of values, or an
@@ -1323,19 +1428,34 @@ module Permittable
     # enum rule all read the members the runtime compares against. A member
     # no request value could ever equal is a contract mistake, and fails here
     # rather than as an `inclusion` on every request.
+    #
+    # An empty list or a reversed Range is refused for the same reason, but
+    # an object used as given is not asked: it is read on every request, so
+    # a live registry that is empty now (filled in an initializer or
+    # `after_initialize`, after `eager_load!` has run this) is the very use
+    # the README recommends it for.
     def resolve_in!(field)
       name = field[:name]
       allowed = field[:in]
       if allowed.is_a?(Range)
         assert_comparable_range!(field, allowed)
+        assert_satisfiable!(name, :in, allowed)
       elsif (members = Coercion.in_list(allowed))
         cast_in_members!(field, members)
+        assert_satisfiable!(name, :in, field[:in])
       elsif allowed.is_a?(String) || !allowed.respond_to?(:include?)
         raise ArgumentError, "#{LABEL}: :in for field :#{name} must be a Range, a list of values (an Array, Set, " \
                              "or a Hash read as its keys), or an object answering include? " \
                              "(got #{allowed.inspect})#{string_in_hint(allowed)}"
       end
-      assert_satisfiable!(name, :in, field[:in])
+    end
+
+    # An `in:` that is neither a Range nor a list the gem read and cast
+    # itself, so one resolve_in! kept exactly as given: its contents are the
+    # host's, and unknown at class load.
+    def live_in?(field)
+      allowed = field[:in]
+      !allowed.nil? && !allowed.is_a?(Range) && Coercion.in_list(allowed).nil?
     end
 
     def string_in_hint(allowed)
@@ -1413,6 +1533,7 @@ module Permittable
       validate_json_authored_value!(field, :default)
       validate_json_authored_value!(field, :example)
       validate_message!(field)
+      freeze_desc!(field)
     end
 
     def validate_max_depth!(name, depth)
@@ -1543,7 +1664,7 @@ module Permittable
     # same value gets, and what used to be thrown away: `default: "18"` used
     # to be handed to every request omitting it as the String "18", and
     # `:boolean, default: "false"` gave the app a truthy String.
-    # With a `transform:`, the value is stored exactly AS AUTHORED instead —
+    # With a `transform:`, a default is stored exactly AS AUTHORED instead —
     # `transform:` never runs on a default (see AuthoredValues), so casting it
     # here would silently change its type out from under an author who, per
     # the README, writes such a default in the shape the action should
@@ -1551,6 +1672,17 @@ module Permittable
     # :string field means the app gets the Integer 25 either way, whether the
     # request sent "25" (cast then transformed) or omitted the field
     # (authored as the already-final Integer).
+    #
+    # An `example:` is cast either way. It documents what a client SENDS and
+    # never reaches the action, so that reason does not apply to it: under
+    # `transform:` it used to be published uncast, `"type": "integer",
+    # "examples": ["18"]`, the very lie the cast exists to stop.
+    #
+    # The one rule not checked is `in:` when it is an object used as given
+    # (see resolve_in!): a live registry is empty at class load, so
+    # `in: LIVE, default: "order.paid"` would be refused for a member it will
+    # hold by the first request. What it will contain is unknown then, so its
+    # `include?` is not asked; every other rule is still checked.
     def validate_authored_value!(field, opt)
       return unless field.key?(opt)
       return if authored_nil!(field, opt)
@@ -1559,10 +1691,10 @@ module Permittable
       # proc cannot rewrite the host's own literal.
       authored = field[opt].is_a?(String) ? field[opt].dup : field[opt]
       value = Coercion.apply_normalize(field[:normalize], authored)
-      status, result = Coercion.check_scalar(field, value)
+      status, result = Coercion.check_scalar(live_in?(field) ? field.except(:in) : field, value)
       raise ArgumentError, "#{LABEL}: :#{opt} for field :#{field[:name]} violates its own contract (#{result})" unless status == :ok
 
-      field[opt] = freeze_authored(field[:transform] ? field[opt] : result)
+      field[opt] = freeze_authored(opt == :default && field[:transform] ? field[opt] : result)
     end
 
     # An array's authored value is validated by the REQUEST walker itself
@@ -1575,27 +1707,61 @@ module Permittable
     # cast only the top level of each element, and got every one of those
     # wrong.
     #
-    # What is STORED follows the same split as a scalar's: without
-    # `transform:`, the walker's read (exactly what a request sending it
-    # gets); with one, the array exactly AS AUTHORED — the walker still runs,
-    # so a declaration mistake (an element `validate:` refuses, a sub-field
-    # default out of bounds) still fails at class load, but its cast result
-    # is discarded rather than stored. The array's OWN `transform:` is
-    # deliberately never run on a default either way; a SUB-FIELD's
-    # `transform:` still runs during that walk, so "the walker's read" above
-    # really is what an equivalent request produces — see AuthoredValues.
+    # What is STORED for a default follows the same split as a scalar's:
+    # without `transform:`, the walker's read (exactly what a request sending
+    # it gets); with one, the array exactly AS AUTHORED — the walker still
+    # runs, so a declaration mistake (an element `validate:` refuses, a
+    # sub-field default out of bounds) still fails at class load, but its
+    # cast result is discarded rather than stored. The array's OWN
+    # `transform:` is deliberately never run on a default either way. A
+    # SUB-FIELD's `transform:` still runs during that walk, so "the walker's
+    # read" above really is what an equivalent request produces: all of them
+    # when the array has no `transform:` of its own, and, when it has one,
+    # those below an array declaring `validate:`, the only readers of their
+    # output (a request runs sub-field transforms, then that `validate:`,
+    # then the array's own transform) — see AuthoredValues.
+    #
+    # An `example:` is validated the same way, as a request would be, but what
+    # is STORED is a second read of it exactly as a client SENDS it: cast and
+    # normalized, with no `transform:` run at any depth and no sub-field
+    # `default:` filled in. Read through a sub-field's transform,
+    # `[{ price: "9.99" }]` under `transform: ->(d) { (d * 100).to_i }` was
+    # published as `[{ "price": 999 }]`: 100 times the price, and a `tags`
+    # split into an Array the server refuses. The two reads cannot be one: an
+    # array-level `validate:` must see the transformed sub-fields a request
+    # hands it (`i[:tags].is_a?(Array)`), so the validating read keeps them,
+    # and the stored read, which runs no `validate:`, discards them.
+    #
+    # The transforming read exists only for that `validate:`, so it runs only
+    # when one could consume it. Anywhere else its output is thrown away, yet
+    # it would still call app code at class load: `optional :id, :string,
+    # transform: ->(s) { Account.find(s) }` under an `example:` hit the
+    # database, or raised, at boot. Only an array carries a `validate:` that
+    # sees its transformed children: a scalar's or a :json field's runs on
+    # its own value before its own transform, and a nested hash takes none.
+    # Without one, the as-sent read both validates and is stored.
     def validate_array_authored_value!(field, opt)
       value = field[opt]
       return if authored_nil!(field, opt)
       raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} must be an Array" unless value.is_a?(Array)
 
-      read, violations = AuthoredValues.read_array(field, value)
+      as_sent = opt == :example && !array_validate_in?(field)
+      read, violations = AuthoredValues.read_array(field, value, as_sent: as_sent)
       unless violations.empty?
         raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} violates its own contract: " \
                              "#{AuthoredValues.summary(violations)}"
       end
 
-      field[opt] = freeze_authored(field[:transform] ? value : read)
+      read, = AuthoredValues.read_array(field, value, as_sent: true) if opt == :example && !as_sent
+      field[opt] = freeze_authored(opt == :default && field[:transform] ? value : read)
+    end
+
+    # Whether `field`, or any array or nested hash below it, declares an
+    # array-level `validate:`.
+    def array_validate_in?(field)
+      return true if field[:kind] == :array && field[:validate]
+
+      Array(field[:fields]).any? { |sub| array_validate_in?(sub) }
     end
 
     # A contract is frozen data, but `@fields.map(&:freeze)` freezes only the
@@ -1634,6 +1800,18 @@ module Permittable
             "declare nullable: true to make an explicit null part of the contract"
     end
 
+    # `desc:` is exported as the schema's `description`, and was handed out
+    # by reference: a caller appending to a generated document's
+    # description (" (deprecated)", a gsub! for localisation) rewrote the
+    # contract inside the frozen rule, and every later export in the process
+    # carried the edit. Frozen as a copy, like message:, default: and
+    # example:, so the host's own String is left as it passed it. The
+    # exporters hand out an unfrozen `dup` of it, so editing a generated
+    # document in place works and still cannot reach the contract.
+    def freeze_desc!(field)
+      field[:desc] = freeze_authored(field[:desc]) unless field[:desc].nil?
+    end
+
     # `message:` customizes what the client reads for a violation on this
     # field: one String covering every code, or a Hash of code => String
     # (codes without an entry keep the default rendering). Keys are
@@ -1733,7 +1911,7 @@ module Permittable
 
       rule = { actions: actions.flatten.map(&:to_s).freeze, root: root && root.to_sym,
                model: model_class, unknown: unknown, enforce: !!enforce, mode: mode, fields: fields,
-               finalize: builder.finalizer, desc: desc }.freeze
+               finalize: builder.finalizer, desc: desc&.deep_dup&.freeze }.freeze
       self.permittable_contracts = permittable_contracts + [rule]
     end
 
@@ -1780,10 +1958,11 @@ module Permittable
 
       types = checked.to_h { |f| [f[:name], f[:type]] }
       allowed = checked.select { |f| f.key?(:in) }.to_h { |f| [f[:name], f[:in]] }
+      transformed = checked.select { |f| f[:transform] }.map { |f| f[:name].to_sym }
       begin
         ColumnGuard.ensure_columns_on!(LABEL, model_class, *checked.map { |f| f[:name] },
                                        types: types, check_types: Permittable.check_column_types,
-                                       allowed: allowed)
+                                       allowed: allowed, transformed: transformed)
       rescue ArgumentError => e
         # The type error carries its own guidance; only the missing-column one
         # needs the virtual: hint appended.
@@ -1858,10 +2037,33 @@ module Permittable
     return nil unless action
 
     rule = self.class.permit_rule_for(action)
-    permitted_params(action) if rule && (rule[:enforce] || permittable_mode(rule) == :monitor)
+    return nil unless rule
+
+    if permittable_mode(rule) == :monitor
+      permittable_monitor_eagerly(action)
+    elsif rule[:enforce]
+      permitted_params(action)
+    end
     nil
   end
 
+  # Monitor mode's promise is that the action runs, whatever the request
+  # holds — that is what makes it safe to turn on. Checking eagerly reads
+  # `params`, which raises ActionDispatch's ParseError on a body Rails
+  # cannot parse: a webhook action reading request.raw_post itself got a
+  # 400 instead of running. An exception from the contract's own code
+  # (validate:, transform:, finalize) became a 500 the same way. Either is
+  # now logged, by class only (a parse error's message can quote the body),
+  # and the action runs; one that reads permitted_params meets the same
+  # exception itself, as it would with no contract at all.
+  def permittable_monitor_eagerly(action)
+    permitted_params(action)
+  rescue StandardError => e
+    return unless respond_to?(:logger) && logger
+
+    logger.warn("#{LABEL}: [monitor] ##{action} could not be checked: #{e.class} — the action runs unchecked")
+  end
+
   # The violation details recorded by validating `action` (default: the
   # current action) — [] when the request satisfied the contract. Triggers
   # the same memoized validation as permitted_params, so under monitor mode
@@ -1891,38 +2093,74 @@ module Permittable
     )
   end
 
-  private
-
   # ParamsWrapper copies a JSON body under the controller's wrapper key
   # (`user` for UsersController) — on by default in a Rails app — and a
   # rootless contract then saw that copy as an unknown top-level key on every
-  # well-formed request. Whether the copy is Rails' own has to be read HERE,
-  # before ParamsWrapper#process_action (next in the chain) runs: once it has
-  # wrapped, `_wrapper_enabled?` answers false, because params now carry the
-  # key. Asking afterwards could not tell Rails' copy from a client that sent
-  # `user` itself, which is exactly the key the check must still flag.
-  # Private, like the method it wraps — a public one would become an action.
-  # A plain duck has no process_action and no ParamsWrapper, so this never
-  # runs there, and the guards keep an actionpack-free host inert.
+  # well-formed request. Whether the copy is Rails' own has to be read before
+  # ParamsWrapper#process_action wraps: afterwards `_wrapper_enabled?` answers
+  # false, because params now carry the key, and nothing left in the request
+  # tells Rails' copy from a client that sent `user` itself, which is exactly
+  # the key the check must still flag. (Comparing the key's value with what
+  # the wrapper would have built only guesses: a client can send that value.)
+  #
+  # So it is read here, in `process`, not in process_action. Every
+  # process_action, ParamsWrapper's included, runs inside
+  # AbstractController::Base#process, so no module order can put the
+  # wrapping first. A process_action hook relied on Rails' own order:
+  # ActionController::Base includes ParamsWrapper, so an
+  # ApplicationController's Permittable runs before it. A Metal controller
+  # that includes ParamsWrapper AFTER Permittable (in a subclass, say) ran
+  # ParamsWrapper's process_action first, and every wrapped JSON request was
+  # a 422 again.
+  #
+  # Public, like the method it wraps, so a caller that sends `process`
+  # explicitly still can. It never becomes an action:
+  # AbstractController::Base#process is a public method of every abstract
+  # controller class (Metal, Base, API), and action_methods leaves those out
+  # as internal. On a plain duck, which has no ParamsWrapper, the guards
+  # make it a pass-through to whatever `process` the host has.
   # Assigned on every request, never only when true: a controller instance
   # dispatched twice would otherwise carry one request's exemption into the
   # next, where a `user` the client did send would pass as Rails' copy.
-  def process_action(*)
+  def process(...)
     @permittable_wrapper_key = permittable_wrapper_copy_key
     super
   end
 
-  # The wrapper key, if ParamsWrapper is about to copy the body under it;
-  # nil otherwise. `_wrapper_enabled?` alone is not enough: it asks the
-  # string-keyed params for the key AS CONFIGURED, so `wrap_parameters :user`
-  # — the form the Rails docs use — answers "not sent" even when the client
-  # sent `user` itself, and Rails wraps anyway. Asking the same params for
-  # the String keeps that client's key the client's, whichever spelling the
-  # host chose.
+  private
+
+  # The wrapper key, if ParamsWrapper is about to copy the body under it and
+  # a contract on this controller would act on that; nil otherwise.
+  #
+  # The request is asked only when the answer can matter. A controller none
+  # of whose contracts reads its input without the copy (see
+  # permittable_drops_wrapper_copy?) — only rooted contracts, say, or the
+  # default `unknown: :ignore` with no field of the wrapper's name — paid a
+  # content-type lookup and a params read on every request for nothing.
+  # Everything the gate reads is class-level (the wrapper's formats and name,
+  # and the contracts), so a skipped probe touches nothing of the request.
+  # The formats come first, in ParamsWrapper's own order: with none it never
+  # wraps and never asks for its name — which it could not give, an
+  # unconfigured wrapper having no controller to derive one from. The
+  # contract gate is ALL of the controller's contracts, not only the one
+  # covering this action: permitted_params(:create) can read another
+  # action's contract from inside #update, and by then ParamsWrapper has
+  # wrapped and the question can no longer be answered.
+  #
+  # `_wrapper_enabled?` asks the params for the key as configured. Rails'
+  # params are indifferent on every supported version, so that already
+  # covers `wrap_parameters :user` and "user" alike. Asking again for the
+  # String keeps a client's `user` the client's on a plain string-keyed
+  # params Hash too — one a test seeds into the request directly — where
+  # :user would answer "not sent" and ParamsWrapper would wrap anyway.
   def permittable_wrapper_copy_key
-    return unless respond_to?(:_wrapper_enabled?, true) && respond_to?(:_wrapper_key, true) && _wrapper_enabled?
+    return unless %i[_wrapper_enabled? _wrapper_formats _wrapper_key].all? { |name| respond_to?(name, true) }
+    return if _wrapper_formats.empty?
+
+    key = _wrapper_key&.to_s
+    return unless key && self.class.permittable_contracts.any? { |rule| permittable_drops_wrapper_copy?(rule, key) }
+    return unless _wrapper_enabled?
 
-    key = _wrapper_key.to_s
     key unless request.parameters.key?(key)
   end
 
@@ -1944,7 +2182,7 @@ module Permittable
     source = permittable_root_hash(rule, violations)
     result = ActiveSupport::HashWithIndifferentAccess.new
     if source
-      checked = rule[:root] ? source : permittable_without_wrapper_copy(rule[:fields], source)
+      checked = permittable_without_wrapper_copy(rule, source)
       result = permittable_check_hash(rule[:fields], checked, path: rule[:root] ? rule[:root].to_s : nil,
                                                               unknown: rule[:unknown], top_level: !rule[:root], violations: violations)
     end
@@ -2223,6 +2461,7 @@ module Permittable
         violations << permittable_violation(field, full, "invalid_type")
       end
     when :array
+      value = value.values if permittable_fields_for_records?(field, value)
       if value.is_a?(Array)
         result[key] = permittable_check_array(field, value, path: full, unknown: unknown, violations: violations)
       else
@@ -2231,6 +2470,20 @@ module Permittable
     end
   end
 
+  # Whether `value` is an array of hashes sent the way Rails' fields_for
+  # sends one: `user[addresses_attributes][0][city]` reaches the params as a
+  # Hash keyed "0", "1", ... (or a timestamp, for a record added in the
+  # browser). Strong params permits exactly this shape (its
+  # fields_for_style?: every key an integer, every value a hash) and
+  # accepts_nested_attributes_for reads its values in order, so an
+  # `array ... do` field reads them as its elements. Paths then count the
+  # records in the order sent. An empty Hash, or one of scalars, is not this
+  # shape and stays invalid_type.
+  def permittable_fields_for_records?(field, value)
+    field[:fields] && value.is_a?(Hash) && !value.empty? &&
+      value.all? { |key, record| key.to_s.match?(/\A-?\d+\z/) && record.is_a?(Hash) }
+  end
+
   # Coercion.check_json, with the copy the result needs made in the middle.
   # The opaque hash is handed over whole, and HashWithIndifferentAccess
   # rebuilt its containers but not the Strings inside them, so it is
@@ -2293,8 +2546,9 @@ module Permittable
     # NOTHING violated, validate: included — a transform may rely on what
     # validate: checked (`Math.sqrt` after "all positive").
     elements_valid = violations.drop(before).all? { |v| permittable_unknown_key_violation?(v) }
-    if field[:validate] && elements_valid
-      status, code = Coercion.check_custom(field[:validate], out)
+    validator = permittable_array_validator(field)
+    if validator && elements_valid
+      status, code = Coercion.check_custom(validator, out)
       violations << permittable_violation(field, path, code) unless status == :ok
     end
     # Transform only a fully-valid array — a partially-nil one (element
@@ -2309,6 +2563,11 @@ module Permittable
     field[:transform] ? field[:transform].call(value) : value
   end
 
+  # A second seam, for the same reader: the array-level `validate:` to run.
+  def permittable_array_validator(field)
+    field[:validate]
+  end
+
   def permittable_check_element(field, element, path, unknown:, violations:)
     if field[:fields]
       unless element.is_a?(Hash)
@@ -2385,6 +2644,7 @@ module Permittable
     if top_level
       extra -= UNCHECKED_TOP_LEVEL_KEYS + permittable_request_supplied_keys
       extra -= [permittable_configured_csrf_key].compact
+      extra -= permittable_image_submit_keys(hash, extra)
     end
     return if extra.empty?
 
@@ -2410,6 +2670,33 @@ module Permittable
     request.path_parameters.keys.map(&:to_s)
   end
 
+  # The click point of an image submit among `keys` (the undeclared top-level
+  # keys). image_submit_tag renders <input type="image">, and a browser
+  # submitting through it posts where it was clicked: `x=12&y=7`, or
+  # `save.x=12&save.y=7` when the tag is named "save" (Rack keeps a dotted
+  # key as it is). Like the other FORM_KEYS these are the framework's own
+  # keys, so `unknown: :error` must not fail the form for them. Unlike them
+  # `x` and `y` are ordinary names a contract may really be sent, so a
+  # lone `x` is still flagged: a point is exempt only as a PAIR, both of
+  # them in `keys` (a declared `x` or `y` is not, and is checked as a field)
+  # and both digits, which is all a browser sends (coordinates are never
+  # negative or fractional). Read by bytes, since a client's key or value can
+  # be invalid UTF-8, which a regexp refuses to match, or another encoding
+  # altogether (a UTF-16 key makes `end_with?` raise).
+  def permittable_image_submit_keys(hash, keys)
+    by_bytes = keys.to_h { |key| [key.b, key] }
+    by_bytes.each_with_object([]) do |(bytes, key), point|
+      next unless bytes == "x" || bytes.end_with?(".x")
+
+      partner = by_bytes["#{bytes.delete_suffix('x')}y"]
+      point.push(key, partner) if partner && [key, partner].all? { |name| permittable_digits?(hash[name]) }
+    end
+  end
+
+  def permittable_digits?(value)
+    value.is_a?(String) && !value.empty? && value.each_byte.all? { |byte| byte.between?(48, 57) }
+  end
+
   # FORM_KEYS bakes in "authenticity_token" — Rails' DEFAULT CSRF parameter
   # name — but `config.action_controller.request_forgery_protection_token`
   # lets an app rename it, and an app that does trips `unknown: :error` on
@@ -2429,28 +2716,39 @@ module Permittable
     token && token.to_s
   end
 
-  # A rootless contract's input without ParamsWrapper's copy of the body,
-  # when Rails made one (see process_action). Removed rather than merely
-  # exempted from the unknown-keys check, because the client never sent that
-  # key: a contract that happens to declare a scalar or array field of the
+  # A contract's input without ParamsWrapper's copy of the body, when Rails
+  # made one (see process) and the contract reads its input without it (see
+  # permittable_drops_wrapper_copy?). Removed rather than merely exempted
+  # from the unknown-keys check, because the client never sent that key: a
+  # contract that happens to declare a scalar or array field of the
   # wrapper's name (`optional :feedback, :string` on FeedbackController)
   # would otherwise validate Rails' copy of the whole body as that field — a
-  # false 422 invalid_type for a well-formed request.
-  #
-  # Kept, though, when the contract declares that key as a hash container (a
-  # nested block or :json): that rootless contract is reading the copy ON
-  # PURPOSE, a root: spelled as a field, and it worked that way before the
-  # copy was ever dropped — dropping it would turn every such request into
-  # `user missing`. Top level only, where the copy lives; a rooted contract
-  # reads the copy as its root, which is exactly what ParamsWrapper is for.
-  # What is checked changes, not what monitor mode hands back: its raw
-  # pass-through still carries the copy, as the pre-contract app's params did.
-  def permittable_without_wrapper_copy(fields, source)
+  # false 422 invalid_type for a well-formed request. Top level only, where
+  # the copy lives. What is checked changes, not what monitor mode hands
+  # back: its raw pass-through still carries the copy, as the pre-contract
+  # app's params did.
+  def permittable_without_wrapper_copy(rule, source)
     key = @permittable_wrapper_key
-    return source unless key
-    return source if fields.any? { |f| f[:name].to_s == key && WRAPPER_CONTAINER_KINDS.include?(f[:kind]) }
+    key && permittable_drops_wrapper_copy?(rule, key) ? source.except(key) : source
+  end
 
-    source.except(key)
+  # Whether `rule` reads its input without ParamsWrapper's copy under `key`
+  # — and so whether the probe's answer changes anything for it, which is
+  # why permittable_wrapper_copy_key asks this too before touching the
+  # request. Not for a rooted contract: it reads the copy as its root, which
+  # is exactly what ParamsWrapper is for. Not for a rootless one declaring
+  # `key` as a hash container (a nested block or :json) either: that
+  # contract is reading the copy ON PURPOSE, a root: spelled as a field, and
+  # it worked that way before the copy was ever dropped — dropping it would
+  # turn every such request into `user missing`. Any other field of that
+  # name would validate the copy, so the copy goes whatever the unknown:
+  # mode. Undeclared, it would only be flagged as unknown, which
+  # `unknown: :ignore` never does, so there the copy changes nothing.
+  def permittable_drops_wrapper_copy?(rule, key)
+    return false if rule[:root]
+
+    field = rule[:fields].find { |f| f[:name].to_s == key }
+    field ? !WRAPPER_CONTAINER_KINDS.include?(field[:kind]) : rule[:unknown] != :ignore
   end
 
   def permittable_path(path, key)