permittable 0.6.0 → 0.8.0

data/lib/permittable.rb

@@ -4,8 +4,21 @@ require "active_support/notifications"
 require "active_support/hash_with_indifferent_access"
 require "active_support/core_ext/hash/indifferent_access" # nested plain Hashes inside HWIA.new
 require "active_support/core_ext/class/attribute"
+require "active_support/core_ext/object/deep_dup" # authored default:/example: values are copied before freezing
 require "active_support/core_ext/string/inflections"
 require "active_support/core_ext/string/filters"
+# cast_datetime names ActiveSupport::TimeWithZone, which activesupport does not
+# load by default. A Rails app has it via active_support/time at boot; a
+# standalone host (a Contract validating a webhook payload or a job argument)
+# has nothing that loads it, and every :datetime cast raised NameError there.
+#
+# The Time core extensions come with it, and are not optional: TimeWithZone is
+# present but not self-sufficient. Converting one goes through
+# TimeZone#utc_to_local, which calls Time#sec_fraction — defined in
+# core_ext/time/calculations, which time_with_zone.rb does not itself require.
+# Without this line a real TimeWithZone raises NoMethodError in a bare host on
+# activesupport 8.1, having merely traded one crash for another.
+require "active_support/core_ext/time/calculations"
 require "bigdecimal"
 require "date"
 require "time"
@@ -98,7 +111,12 @@ require "permittable/filter_parameter_registry"
 # guess. nil and "" are both treated as ABSENT (the query-param convention):
 # absent optional fields are OMITTED from the result (so partial updates never
 # nil-out columns), absent required fields violate, and `default:` fills
-# absence.
+# absence. `normalize:` runs BEFORE that rule rather than inside the cast, so
+# there is exactly one reading of absence and a value that normalizes to empty
+# ("   " under :squish) cannot satisfy a required field by becoming "". An
+# authored `default:`/`example:` is stored normalized — the form it was
+# validated in — and deep-frozen on a 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
 # clears a column: a key the client never sent stays absent (defaults apply,
@@ -127,7 +145,19 @@ require "permittable/filter_parameter_registry"
 # `sensitive: true` registers the field name with
 # Permittable.filter_parameter_registry (swappable — a host gem can point it
 # at its own registry), consulted at filter time by the proc
-# Permittable::Railtie appends to `config.filter_parameters`.
+# Permittable::Railtie appends to `config.filter_parameters`. The name is
+# ALSO published to that Railtie by name (see register_sensitive_parameter),
+# because a proc filter can only redact String values — ActiveSupport dups
+# the value and expects in-place mutation, and never calls the proc at all
+# for a Hash — so a name in config.filter_parameters is what covers an
+# :integer field or a sensitive nested block.
+# Permittable::Railtie appends to `config.filter_parameters`. On a nested or
+# array field it CASCADES to every field inside, because Rails' filtering
+# asks about the leaf key it is looking at rather than the path to it; a
+# sub-field opts out with `sensitive: false`, since matching is a substring
+# match and a generic cascaded name would redact half the app's logs. The
+# cascade is resolved onto the field data at class load — see
+# ContractBuilder#cascade_sensitive.
 #
 # OUTPUT RESHAPING — the safe replacement for params-mutating before_actions.
 # Two layers, both operating on the validated COPY (the request's `params` is
@@ -162,6 +192,40 @@ module Permittable
   # 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
+  # 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
+  # rather than leaving a bare ROUTING_KEYS to read like an oversight.
+  UNCHECKED_TOP_LEVEL_KEYS = (ROUTING_KEYS + FORM_KEYS).freeze
+  MONITOR_DROPPED_KEYS = ROUTING_KEYS
+  # 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
+  # write a megabyte of them. The machine-readable channels — a violation's
+  # `details` and the instrumentation payload — stay complete; only the
+  # sentence is bounded.
+  PROSE_LIST_LIMIT = 10
+  # ...and each name it does list is truncated. Capping the COUNT alone still
+  # let ONE 1 MB key name write the 1 MB log line the cap exists to prevent.
+  PROSE_ITEM_LIMIT = 120
+
+  # The single proc Permittable::Railtie appends to config.filter_parameters.
+  # Declared with an optional third parameter so its own arity is -3 and Rails
+  # passes `original_params`; the registry's callable is then invoked by ITS
+  # arity, so both the 2- and 3-argument proc-filter shapes Rails accepts work
+  # as a swapped-in registry's #to_proc.
+  FILTER_PARAMETER_PROC = lambda do |key, value, original = nil|
+    inner = filter_parameter_registry.to_proc
+    inner.arity == 2 ? inner.call(key, value) : inner.call(key, value, original)
+  end.freeze
 
   NORMALIZERS = {
     squish: ->(v) { v.squish },
@@ -183,7 +247,84 @@ module Permittable
       end
     end
 
-    attr_writer :filter_parameter_registry
+    # Swapping registries must not un-redact anything. Contracts that loaded
+    # BEFORE the swap registered on the outgoing registry, and after the swap
+    # nothing consults it any more — so its entries are carried into the new
+    # one, which is the mirror image of the bug that made the proc late-bound
+    # in the first place. Validated here rather than at filter time: a
+    # registry with no #to_proc used to be silently never consulted, and
+    # late-binding it would instead raise NoMethodError on every request.
+    def filter_parameter_registry=(registry)
+      unless registry.nil? || registry.respond_to?(:to_proc)
+        raise ArgumentError,
+              "#{LABEL}: filter_parameter_registry must respond to #to_proc (got #{registry.class})"
+      end
+
+      @registry_mutex.synchronize do
+        previous = @filter_parameter_registry
+        @filter_parameter_registry = registry
+        next unless registry && previous.respond_to?(:names) && registry.respond_to?(:add)
+
+        previous.names.each { |name| registry.add(name) }
+      end
+      registry
+    end
+
+    # The proc Permittable::Railtie appends to config.filter_parameters.
+    #
+    # It resolves the registry at FILTER time rather than closing over
+    # whichever instance existed at boot. Rails runs railtie initializers
+    # BEFORE config/initializers, so an app or host gem that swaps the
+    # registry — the pooling the writer exists for — necessarily does so
+    # after the Railtie has already appended its proc. A proc bound to the old
+    # instance would go on consulting an empty registry and silently redact
+    # nothing, while `sensitive:` fields registered themselves in the new one.
+    #
+    # One frozen object for the life of the process, so the Railtie's
+    # idempotence check (include? before <<) holds across repeated initializer
+    # runs with no memo to synchronise.
+    def filter_parameter_proc
+      FILTER_PARAMETER_PROC
+    end
+
+    # Every `sensitive:` registration, published to whatever is listening.
+    #
+    # A proc filter cannot be the whole mechanism: ActiveSupport's
+    # ParameterFilter dups the value and expects in-place mutation, so a proc
+    # can only redact Strings — and it is never even CALLED for a Hash value,
+    # because ParameterFilter checks `value.is_a?(Hash)` first and recurses.
+    # So `optional :pin, :integer, sensitive: true` and `sensitive:` on a
+    # nested block both logged in the clear. What redacts any value type is a
+    # NAME in config.filter_parameters, which only Rails can be told about —
+    # hence a sink, installed by Permittable::Railtie, rather than Rails
+    # knowledge in this file or in the registry.
+    def register_sensitive_parameter(name)
+      filter_parameter_registry.add(name)
+      # Normalized the way the registry normalizes, so the name a sink sees is
+      # the same whether it arrives here or through on_sensitive_parameter's
+      # replay of #names — otherwise a sink deduplicating by value would hold
+      # both :ssn and "ssn".
+      name = name.to_s.downcase
+      sensitive_parameter_sinks.each { |sink| sink.call(name) } unless name.empty?
+      nil
+    end
+
+    # Install a sink. It is replayed over the names already registered, since
+    # a contract can be declared before the Railtie's initializer runs (a
+    # Permittable::Contract at require time, an eager-loaded controller) and
+    # would otherwise never reach it.
+    def on_sensitive_parameter(&sink)
+      @registry_mutex.synchronize { sensitive_parameter_sinks << sink }
+      registry = filter_parameter_registry
+      registry.names.each { |name| sink.call(name) } if registry.respond_to?(:names)
+      sink
+    end
+
+    # The installed sinks. Process-global, like the registry — specs that
+    # install one `.clear` this afterwards.
+    def sensitive_parameter_sinks
+      @sensitive_parameter_sinks ||= []
+    end
 
     # App-wide default for rules that don't declare their own mode:.
     # :enforce (the default) rejects violating requests; :monitor reports
@@ -250,20 +391,34 @@ module Permittable
     TRUE_VALUES = [true, "true", "1", 1].freeze
     FALSE_VALUES = [false, "false", "0", 0].freeze
 
-    # Full pipeline for one scalar field: normalize → cast → in / format /
-    # length / validate.
+    # Pipeline for one scalar field: cast → in / format / length / validate.
+    # `normalize:` is NOT applied here — it is its own stage, run by the
+    # caller before the absence rule (a value that normalizes to "" is absent
+    # like any other empty value), so normalizing again here would call a
+    # host's `normalize:` proc twice per value.
     def check_scalar(field, value)
-      value = apply_normalize(field[:normalize], value)
       status, value = cast(field[:type], value)
       return [status, value] unless status == :ok
 
       check_scalar_rules(field, value)
     end
 
+    # `length:` first, deliberately. It is an O(1) read of a String's size,
+    # while `format:` runs a regexp over the whole value and `validate:` runs
+    # arbitrary app code — so checking the cheap bound last meant a value the
+    # bound already excluded still paid for the expensive ones. A 5 MB string
+    # against `length: 1..80` scanned all 5 MB with the field's regexp before
+    # being rejected on its length, and an app regexp with poor worst-case
+    # behaviour turns that from waste into a lever.
+    #
+    # The only observable change is which code a value violating BOTH reports:
+    # `length` now, rather than `inclusion`/`format`. Reporting the structural
+    # failure first is the better answer anyway — a client cannot act on
+    # "wrong format" for a value that is also far too long.
     def check_scalar_rules(field, value)
+      return [:error, "length"] if field[:length] && !length_ok?(field[:length], value.length)
       return [:error, "inclusion"] if field[:in] && !included_in?(field[:in], value)
       return [:error, "format"] if field[:format] && !field[:format].match?(value)
-      return [:error, "length"] if field[:length] && !length_ok?(field[:length], value.length)
 
       check_custom(field[:validate], value)
     end
@@ -342,23 +497,54 @@ module Permittable
 
     def cast_float(value)
       case value
-      when Numeric then [:ok, value.to_f]
-      when String then [:ok, Float(value)]
+      when Numeric then finite_float(value.to_f)
+      when String then finite_float(Float(value), source: value)
       else [:error, "invalid_type"]
       end
     rescue ArgumentError
       [:error, "invalid_type"]
     end
 
+    # A Float that is not finite does not represent what was sent. "1e400"
+    # overflows to Infinity and "1e-400" underflows to zero — both silently,
+    # and both leaving a value no column can faithfully store.
+    #
+    # Underflow is only visible against the source text, since the result is
+    # an ordinary 0.0: a zero result is rejected when the string it came from
+    # named a nonzero SIGNIFICAND. Only the significand, because "0e10" is a
+    # genuine zero whose exponent digits say nothing about the value — as are
+    # "0", "0.0" and "0.0000".
+    def finite_float(result, source: nil)
+      return [:error, "invalid_type"] unless result.finite?
+      return [:error, "invalid_type"] if result.zero? && nonzero_significand?(source)
+
+      [:ok, result]
+    end
+
+    def nonzero_significand?(source)
+      return false unless source
+
+      source.split(/[eE]/, 2).first.match?(/[1-9]/)
+    end
+
     def cast_decimal(value)
       case value
-      when Numeric, String then [:ok, BigDecimal(value.to_s)]
+      when Numeric, String then finite_decimal(BigDecimal(value.to_s))
       else [:error, "invalid_type"]
       end
     rescue ArgumentError
       [:error, "invalid_type"]
     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
+    # have it stored. Nothing else in the gem disagreed with itself this
+    # loudly: :float rejected those strings and :decimal did not.
+    def finite_decimal(result)
+      result.finite? ? [:ok, result] : [:error, "invalid_type"]
+    end
+
     def cast_boolean(value)
       return [:ok, true] if TRUE_VALUES.include?(value)
       return [:ok, false] if FALSE_VALUES.include?(value)
@@ -402,7 +588,12 @@ module Permittable
     def cast_datetime(value)
       case value
       # DateTime is listed here, ahead of Date, because it subclasses Date.
-      when ActiveSupport::TimeWithZone, Time, DateTime then [:ok, value.to_time.utc]
+      # `getutc` rather than `utc`: `Time#utc` converts the RECEIVER, and
+      # `Time#to_time` returns self, so `value.to_time.utc` silently rewrote
+      # the caller's own object. A TimeWithZone's `getutc` hands back the
+      # instance it caches internally, so that one is duped.
+      when ActiveSupport::TimeWithZone then [:ok, value.getutc.dup]
+      when Time, DateTime then [:ok, value.to_time.getutc]
       when Date then [:ok, Time.utc(value.year, value.month, value.day)]
       when String
         # Same rule as :date — the DATE part must be named in full, or it is
@@ -429,6 +620,14 @@ module Permittable
       normalizer.call(value)
     end
 
+    # nil and "" are both ABSENT — see the module comment. The VALUE half of
+    # that rule (the walker adds the key-presence half), shared with
+    # macro-time `default:`/`example:` checking so a default cannot be held
+    # to a different reading of absence than the request it stands in for.
+    def absent_value?(value)
+      value.nil? || (value.is_a?(String) && value.empty?)
+    end
+
     # Range#include? walks discrete ranges; cover? is the O(1) bounds check
     # and the right semantics for validation.
     def included_in?(allowed, value)
@@ -495,7 +694,7 @@ module Permittable
       if block
         raise ArgumentError, "#{LABEL}: array :#{name} takes of: OR a block, not both" if opts.key?(:of)
 
-        field[:fields] = nested_fields!(name, &block)
+        field[:fields] = cascade_sensitive(nested_fields!(name, &block), field[:sensitive])
         field.delete(:of)
       else
         field[:of] = scalar_type!(name, opts[:of] || :string)
@@ -519,6 +718,7 @@ module Permittable
         assert_opts!(name, opts, NESTED_OPTS)
         field = { name: name, kind: :nested, required: required,
                   fields: nested_fields!(name, &block), **opts }
+        field[:fields] = cascade_sensitive(field[:fields], field[:sensitive])
         validate_message!(field)
       elsif type&.to_sym == JSON_TYPE
         assert_opts!(name, opts, JSON_OPTS)
@@ -570,17 +770,60 @@ module Permittable
       fields
     end
 
+    # `sensitive: true` on a nested or array field CASCADES to every field
+    # inside it, and the cascade is resolved HERE, at class load, so that
+    # `field[:sensitive]` stays the single source of truth every reader
+    # consults: the filter registry, the exported schema's `writeOnly`, and
+    # the RSpec matcher's `.sensitive` chain. Resolving it privately inside
+    # the registry walk would have redacted a cascaded child at runtime
+    # while the schema and the matcher went on calling it public.
+    #
+    # It has to cascade: ActiveSupport::ParameterFilter recurses into Hash
+    # and Array values itself and consults proc filters only for the LEAVES,
+    # handing each one the leaf's own key and never the path that led there.
+    # So registering only `payment` is asked about `card_number`, which it
+    # does not match, and redacts nothing inside the container.
+    #
+    # A sub-field opts out with an explicit `sensitive: false`, because
+    # matching is a case-insensitive SUBSTRING match and cascading a generic
+    # name (:id, :name) would redact every parameter app-wide that contains
+    # it. Only `false` opts out; `sensitive: nil` reads as "not stated" and
+    # still inherits.
+    def cascade_sensitive(fields, inherited)
+      updated = fields.map { |field| cascade_field_sensitive(field, inherited) }
+      updated.zip(fields).all? { |new_field, old| new_field.equal?(old) } ? fields : updated.freeze
+    end
+
+    def cascade_field_sensitive(field, inherited)
+      declared = field[:sensitive]
+      effective = declared.nil? ? inherited : declared
+      children = field[:fields] ? cascade_sensitive(field[:fields], effective) : nil
+      unchanged = (effective ? declared == true : declared == false || !field.key?(:sensitive)) &&
+                  (children.nil? || children.equal?(field[:fields]))
+      return field if unchanged
+
+      updated = field.merge(sensitive: effective)
+      updated[:fields] = children if children
+      updated.freeze
+    end
+
     def validate_scalar_opts!(field)
       name = field[:name]
       if field[:required] && field.key?(:default)
         raise ArgumentError, "#{LABEL}: field :#{name} is required and cannot have a :default (default implies optional)"
       end
-      if field.key?(:in) && !field[:in].respond_to?(:include?)
-        raise ArgumentError, "#{LABEL}: :in for field :#{name} must respond to include? (Range or Array)"
+
+      if field.key?(:in)
+        unless field[:in].respond_to?(:include?)
+          raise ArgumentError, "#{LABEL}: :in for field :#{name} must respond to include? (Range or Array)"
+        end
+
+        assert_satisfiable!(name, :in, field[:in])
       end
 
       validate_string_only_opts!(field)
       validate_length!(name, field[:length]) if field.key?(:length)
+      validate_required_length!(field)
       validate_callable!(name, :validate, field[:validate]) if field.key?(:validate)
       validate_callable!(name, :transform, field[:transform]) if field.key?(:transform)
       resolve_normalizer!(field)
@@ -618,9 +861,9 @@ module Permittable
       raise ArgumentError, "#{LABEL}: :#{opt} for :#{field[:name]} must be a Hash" unless field[opt].is_a?(Hash)
 
       status, code = Coercion.check_json(field, field[opt])
-      return if status == :ok
+      raise ArgumentError, "#{LABEL}: :#{opt} for field :#{field[:name]} violates its own contract (#{code})" unless status == :ok
 
-      raise ArgumentError, "#{LABEL}: :#{opt} for field :#{field[:name]} violates its own contract (#{code})"
+      field[opt] = freeze_authored(field[opt])
     end
 
     # format / length / normalize reason about characters; on any other
@@ -636,9 +879,49 @@ module Permittable
     end
 
     def validate_length!(name, length)
-      return if length.is_a?(Range) || length.is_a?(Integer)
+      unless length.is_a?(Range) || (length.is_a?(Integer) && !length.negative?)
+        raise ArgumentError, "#{LABEL}: :length for :#{name} must be a non-negative Integer or a Range " \
+                             "(got #{length.inspect})"
+      end
+
+      assert_satisfiable!(name, :length, length)
+    end
+
+    # A reversed Range (5..2), an exclusive Range with equal endpoints
+    # (3...3), or an empty set (in: []) excludes every value there is, so the
+    # field it bounds can never validate. That used to surface as every
+    # request to the action failing on that field — a contract mistake
+    # reported as a client error, once per request, forever. Endless and
+    # beginless Ranges are legitimate bounds, and endpoints that cannot be
+    # compared are left alone rather than guessed at.
+    def assert_satisfiable!(name, opt, bound)
+      return unless unsatisfiable?(bound)
 
-      raise ArgumentError, "#{LABEL}: :length for :#{name} must be a Range or Integer"
+      raise ArgumentError, "#{LABEL}: :#{opt} for :#{name} is empty (#{bound.inspect}) — no value can satisfy it"
+    end
+
+    def unsatisfiable?(bound)
+      return bound.empty? if bound.respond_to?(:empty?)
+      return false unless bound.is_a?(Range) && bound.begin && bound.end
+
+      comparison = bound.begin <=> bound.end
+      return false if comparison.nil?
+
+      bound.exclude_end? ? !comparison.negative? : comparison.positive?
+    end
+
+    # "" is ABSENT and an absent required field violates as missing, so a
+    # required string can never validly be empty: a maximum length of 0
+    # leaves it nothing at all to accept. The exported schema already said
+    # so — minLength 1 alongside maxLength 0 — while nothing refused the
+    # declaration that produced it.
+    def validate_required_length!(field)
+      spec = field[:length]
+      return unless field[:required] && spec
+      return unless Coercion.length_ok?(spec, 0) && !Coercion.length_ok?(spec, 1)
+
+      raise ArgumentError, "#{LABEL}: :length for :#{field[:name]} is 0 on a required field — an absent or " \
+                           "empty value already violates as missing, so nothing could satisfy it"
     end
 
     def validate_callable!(name, opt, value)
@@ -661,22 +944,78 @@ module Permittable
     # An authored value (`default:`, or a documentation `example:`) must
     # satisfy the field's own contract — catching a lie at class load beats
     # shipping it to every request (or publishing it in generated docs).
+    # The authored value is STORED normalized, because that is the form it was
+    # validated in: `default: "  free  "` with `normalize: :squish` was
+    # checked as "free" and used to be handed to requests as "  free  ".
     def validate_authored_value!(field, opt)
       return unless field.key?(opt)
       return if authored_nil!(field, opt)
 
-      status, code = Coercion.check_scalar(field, field[opt])
-      return if status == :ok
+      value = Coercion.apply_normalize(field[:normalize], field[opt])
+      status, code = Coercion.check_scalar(field, value)
+      raise ArgumentError, "#{LABEL}: :#{opt} for field :#{field[:name]} violates its own contract (#{code})" unless status == :ok
 
-      raise ArgumentError, "#{LABEL}: :#{opt} for field :#{field[:name]} violates its own contract (#{code})"
+      field[opt] = freeze_authored(value)
     end
 
     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)
-      return unless field[:of]
+      if field[:length] && !Coercion.length_ok?(field[:length], value.length)
+        raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} violates its own contract (length)"
+      end
+
+      validate_array_elements!(field, opt, value) if field[:of]
+      validate_array_element_hashes!(field, opt, value) if field[:fields]
+      field[opt] = freeze_authored(value)
+    end
+
+    # The nested-block counterpart of the of: element check below. Without it
+    # `field[:of]` was nil for a block array, so its `default:` skipped
+    # validation entirely and whatever was authored went straight to every
+    # request that omitted the key. Shallow in the same way the of: check is:
+    # required sub-fields must be present and scalar ones must satisfy their
+    # own contract, which is what an authored value gets wrong.
+    def validate_array_element_hashes!(field, opt, value)
+      value.each do |element|
+        unless element.is_a?(Hash)
+          raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} contains #{element.class} " \
+                               "where the block declares a hash"
+        end
+
+        # Wrapped the way permittable_check_element wraps an element at
+        # request time, so class load reads keys exactly as a request does.
+        indifferent = ActiveSupport::HashWithIndifferentAccess.new(element)
+        field[:fields].each { |sub| validate_array_element_field!(field, opt, indifferent, sub) }
+      end
+    end
+
+    def validate_array_element_field!(field, opt, element, sub)
+      # Normalized before absence is read, and absence read with the runtime's
+      # own rule: a default: is applied WITHOUT revalidation, so anything this
+      # check waves through is handed to the app unexamined — and "" here used
+      # to mean a default could carry the very value a client is refused.
+      value = Coercion.apply_normalize(sub[:normalize], element[sub[:name]])
+      if Coercion.absent_value?(value)
+        # nullable: splits that rule exactly as permittable_explicit_null?
+        # does — a key present but empty is an explicit null, not an absence.
+        return if sub[:nullable] && element.key?(sub[:name])
+        return unless sub[:required]
+
+        raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} is missing :#{sub[:name]}, " \
+                             "which the block declares as required"
+      end
+      return unless sub[:kind] == :scalar
+
+      status, code = Coercion.check_scalar(sub, value)
+      return if status == :ok
 
+      raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} has :#{sub[:name]} " \
+                           "violating its own contract (#{code})"
+    end
+
+    def validate_array_elements!(field, opt, value)
       value.each do |element|
         status, code = Coercion.cast(field[:of], element)
         next if status == :ok
@@ -685,6 +1024,29 @@ module Permittable
       end
     end
 
+    # A contract is frozen data, but `@fields.map(&:freeze)` freezes only the
+    # field hashes — an authored `default:` or `example:` value stayed
+    # mutable, and HashWithIndifferentAccess hands a non-frozen Array (and
+    # any String) to the result BY REFERENCE. So one request appending to
+    # `permitted_params[:tags]` corrupted the default for every later request
+    # in the process. Freezing a COPY fixes that without freezing an object
+    # the host app passed in and may still be using.
+    def freeze_authored(value)
+      deep_freeze(value.deep_dup)
+    end
+
+    def deep_freeze(value)
+      case value
+      when Hash
+        value.each_pair do |key, element|
+          deep_freeze(key)
+          deep_freeze(element)
+        end
+      when Array then value.each { |element| deep_freeze(element) }
+      end
+      value.freeze
+    end
+
     # An authored nil is only meaningful on a nullable field, where it says
     # "absent means clear" (PUT semantics) rather than "no default". On any
     # other field it is a value nil could never satisfy, so it fails at class
@@ -846,9 +1208,24 @@ module Permittable
       end
     end
 
+    # `sensitive: true` on a nested or array field CASCADES to everything
+    # inside it, because Rails' parameter filtering matches the leaf key it is
+    # currently looking at — never the path that led there. Registering only
+    # the container's own name therefore redacted nothing it promised: the
+    # filter is handed ("payment", {...}), a Hash is not a String so nothing
+    # is replaced, and it then recurses and asks about "card_number", which
+    # was never registered.
+    #
+    # A sub-field opts out with an explicit `sensitive: false`. That escape
+    # hatch exists because matching is a case-insensitive SUBSTRING match, so
+    # cascading a generic name (:id, :name) would redact every parameter
+    # app-wide that happens to contain it — occasionally a worse outcome than
+    # the leak it prevents.
+    # The cascade is already resolved on the field data (see
+    # ContractBuilder#cascade_sensitive), so this only has to read it.
     def register_sensitive_params(fields)
       fields.each do |field|
-        Permittable.filter_parameter_registry.add(field[:name]) if field[:sensitive]
+        Permittable.register_sensitive_parameter(field[:name]) if field[:sensitive]
         register_sensitive_params(field[:fields]) if field[:fields]
       end
     end
@@ -858,18 +1235,31 @@ module Permittable
   # defaulted values for the given action (default: the current action).
   # Absent optional fields are omitted. Raises InvalidParameters on
   # violation; raises ArgumentError when no contract covers the action
-  # (that is a programmer error, not a client error). Memoized per action.
+  # (that is a programmer error, not a client error).
+  #
+  # Memoized per action, and the memo remembers the OUTCOME rather than only
+  # a success: a rejection is stored and re-raised. Validation is therefore
+  # observable exactly once per action per request, which the
+  # "invalid_parameters.permittable" event depends on — memoizing only
+  # successes meant a rejected request that was read twice (an action calling
+  # permittable_violations before permitted_params, say) instrumented twice
+  # and double-counted itself in every dashboard.
   def permitted_params(action = nil)
     action = (action || permittable_action_name).to_s
     raise ArgumentError, "#{LABEL}: no action given and action_name is not set" if action.empty?
 
     @permittable_validated ||= {}
-    return @permittable_validated[action] if @permittable_validated.key?(action)
-
-    rule = self.class.permit_rule_for(action)
-    raise ArgumentError, "#{LABEL}: no params contract declared covering ##{action}" unless rule
+    outcome = @permittable_validated.fetch(action) do
+      @permittable_validated[action] = permittable_outcome_for(action)
+    end
+    # `cause: nil` because a memoized rejection is raised from wherever the
+    # action happens to read the params next — possibly inside a `rescue` of
+    # something unrelated, whose exception Ruby would otherwise adopt as this
+    # error's cause for good. The object and its original backtrace (the
+    # first raise site, where the violation was found) are preserved.
+    raise outcome, cause: nil if outcome.is_a?(InvalidParameters)
 
-    @permittable_validated[action] = validate_params_contract!(rule, action)
+    outcome
   end
 
   # before_action entry point (public so hosts can `skip_before_action
@@ -918,6 +1308,19 @@ module Permittable
 
   private
 
+  # The value permitted_params memoizes: the validated params, or the
+  # InvalidParameters that rejected them. ArgumentError is deliberately NOT
+  # memoized — a contract that does not cover the action is a bug to fix, not
+  # a verdict on this request, so it raises fresh on every call.
+  def permittable_outcome_for(action)
+    rule = self.class.permit_rule_for(action)
+    raise ArgumentError, "#{LABEL}: no params contract declared covering ##{action}" unless rule
+
+    validate_params_contract!(rule, action)
+  rescue InvalidParameters => e
+    e
+  end
+
   def validate_params_contract!(rule, action)
     violations = []
     source = permittable_root_hash(rule, violations)
@@ -957,7 +1360,7 @@ module Permittable
     return ActiveSupport::HashWithIndifferentAccess.new unless source
 
     passed = ActiveSupport::HashWithIndifferentAccess.new(source)
-    rule[:root] ? passed : passed.except(*ROUTING_KEYS)
+    rule[:root] ? passed : passed.except(*MONITOR_DROPPED_KEYS)
   end
 
   def raise_invalid_parameters!(violations, status:)
@@ -974,7 +1377,25 @@ module Permittable
   end
 
   def permittable_violation_summary(violations)
-    violations.map { |v| v[:message] ? "#{v[:param]} #{v[:message]}" : "#{v[:param]} (#{v[:code]})" }.join(", ")
+    permittable_prose_list(violations) do |v|
+      v[:message] ? "#{v[:param]} #{v[:message]}" : "#{v[:param]} (#{v[:code]})"
+    end
+  end
+
+  # See PROSE_LIST_LIMIT. `unknown: :error` on a request carrying 50,000
+  # undeclared keys used to produce a 50,000-item sentence — a megabyte of
+  # log line, or of exception message handed to every error tracker.
+  # The block formats one item, and is called only for the items actually
+  # shown — the rest are counted, never rendered.
+  def permittable_prose_list(items)
+    shown = items.first(PROSE_LIST_LIMIT).map { |item| permittable_prose_item(yield(item)) }.join(", ")
+    return shown if items.length <= PROSE_LIST_LIMIT
+
+    "#{shown}, and #{items.length - PROSE_LIST_LIMIT} more"
+  end
+
+  def permittable_prose_item(item)
+    item.length <= PROSE_ITEM_LIMIT ? item : "#{item[0, PROSE_ITEM_LIMIT - 3]}..."
   end
 
   # One violation detail entry. A field's `message:` (String, or Hash keyed
@@ -1016,12 +1437,21 @@ module Permittable
     raw = permittable_plain_params
     return raw unless rule[:root]
 
-    value = raw[rule[:root].to_s]
+    key = rule[:root].to_s
+    value = raw[key]
     return value if value.is_a?(Hash)
 
+    # A root that is absent and a root sent with the wrong shape
+    # ({"user": "bob"}) are different client mistakes, and telling a client
+    # that the key it just sent is "missing" sends it looking in the wrong
+    # place. Absence is the gem's own definition of it, so `{"user": ""}`
+    # still reads as missing. Either way the envelope is malformed, so both
+    # remain a 400.
+    #
     # No field declares the root, so message resolution can only come from
     # I18n ({} has no :message).
-    violations << permittable_violation({}, rule[:root].to_s, "missing")
+    code = permittable_absent?(value, raw, key) ? "missing" : "invalid_type"
+    violations << permittable_violation({}, key, code)
     nil
   end
 
@@ -1039,13 +1469,13 @@ module Permittable
     fields.each do |field|
       key = field[:name].to_s
       full = permittable_path(path, key)
-      value = hash[key]
+      value = permittable_normalized(field, hash[key])
 
       if permittable_absent?(value, hash, key)
         if permittable_explicit_null?(field, hash, key)
           result[key] = nil
         elsif field.key?(:default)
-          result[key] = field[:default]
+          result[key] = permittable_default(field)
         elsif field[:required]
           violations << permittable_violation(field, full, "missing")
         end
@@ -1062,6 +1492,7 @@ module Permittable
     key = field[:name].to_s
     case field[:kind]
     when :scalar
+      # Already normalized by permittable_normalized, before the absence rule.
       permittable_check_whole(field, Coercion.check_scalar(field, value), full, result, violations: violations)
     when :json
       permittable_check_whole(field, Coercion.check_json(field, value), full, result, violations: violations)
@@ -1095,8 +1526,18 @@ module Permittable
   end
 
   def permittable_check_array(field, value, path:, unknown:, violations:)
+    # `length:` is a BOUND, not a report. An array outside it is rejected
+    # whatever its contents, so checking those contents can only add work and
+    # noise: a 200k-element payload against `length: 0..10` used to cast every
+    # element, collect 200k more violations, and answer with a multi-megabyte
+    # 422 — for a request already refused by its first check. Stopping here
+    # keeps the cost of an oversized array proportional to rejecting it.
+    if field[:length] && !Coercion.length_ok?(field[:length], value.length)
+      violations << permittable_violation(field, path, "length")
+      return nil
+    end
+
     before = violations.length
-    violations << permittable_violation(field, path, "length") if field[:length] && !Coercion.length_ok?(field[:length], value.length)
     out = value.each_with_index.map do |element, index|
       permittable_check_element(field, element, "#{path}[#{index}]", unknown: unknown, violations: violations)
     end
@@ -1127,9 +1568,30 @@ module Permittable
     nil
   end
 
+  # `normalize:` runs BEFORE the absence rule, not inside the cast, so there
+  # stays exactly ONE reading of absence. Otherwise a value that normalizes to
+  # empty walked straight past it: `required :name, :string, normalize:
+  # :squish` rejected "" as missing but accepted "   " as "" — the silent
+  # corruption strict coercion exists to refuse, delivered by the gem's own
+  # preset. Only scalars take normalize:, and apply_normalize is itself a
+  # no-op without one, so it owns that decision for every caller.
+  def permittable_normalized(field, value)
+    Coercion.apply_normalize(field[:normalize], value)
+  end
+
+  # An authored default belongs to the contract, which is frozen data (see
+  # ContractBuilder#freeze_authored). HashWithIndifferentAccess copies a
+  # frozen Array or Hash as it assigns it, but stores a String as-is — so
+  # that one is copied here, leaving every value in the result the app's own
+  # to mutate.
+  def permittable_default(field)
+    value = field[:default]
+    value.is_a?(String) ? value.dup : value
+  end
+
   # nil and "" are both ABSENT — see the module comment.
   def permittable_absent?(value, hash, key)
-    !hash.key?(key) || value.nil? || (value.is_a?(String) && value.empty?)
+    !hash.key?(key) || Coercion.absent_value?(value)
   end
 
   # `nullable: true` splits the one absence rule in two: a key the client
@@ -1146,14 +1608,14 @@ module Permittable
 
     declared = fields.map { |f| f[:name].to_s }
     extra = hash.keys.map(&:to_s) - declared
-    extra -= ROUTING_KEYS if top_level
+    extra -= UNCHECKED_TOP_LEVEL_KEYS if top_level
     return if extra.empty?
 
     if unknown == :error
       extra.each { |key| violations << permittable_violation({}, permittable_path(path, key), "unknown") }
     elsif respond_to?(:logger) && logger
-      logger.warn("#{LABEL}: unknown parameter(s) ignored by the ##{permittable_action_name} contract: " \
-                  "#{extra.map { |key| permittable_path(path, key) }.join(', ')}")
+      listed = permittable_prose_list(extra) { |key| permittable_path(path, key) }
+      logger.warn("#{LABEL}: unknown parameter(s) ignored by the ##{permittable_action_name} contract: #{listed}")
     end
   end