permittable 0.11.0 → 0.11.1

data/lib/permittable/json_schema.rb

@@ -16,22 +16,31 @@ module Permittable
   #     the same as `{}`. JSON Schema cannot say that — `type: integer` reads
   #     null as a present value of the wrong type — so the schema rejects a
   #     null the server would accept and ignore.
-  #   * `validate:`/`transform:`/`finalize` are opaque callables — they never
-  #     change what a client may SEND, so fields carrying them are flagged
-  #     with `x-permittable-*` extensions rather than mistranslated.
+  #   * `validate:`/`transform:`/`finalize` are opaque callables the schema
+  #     cannot run, so the field carrying one (or, for `finalize`, the rule's
+  #     own object) is flagged with an `x-permittable-*` extension rather than
+  #     mistranslated. `transform:` only reshapes a value already accepted, so
+  #     it changes no verdict; `validate:` and `finalize` can refuse a value.
   #
-  # All three leave the schema STRICTER than the server, never looser: a
+  # The first two leave the schema STRICTER than the server, never looser: a
   # client that validates against the published document is conservative,
-  # never surprised by a 422. spec/schema_conformance_spec.rb holds that line,
+  # never surprised by a 422. The third does not: `validate:` and `finalize`
+  # leave it LOOSER (below). spec/schema_conformance_spec.rb holds the line,
   # asserting the direction of every divergence it permits.
   #
   # Where a rule has no JSON Schema keyword, the schema is LOOSER instead,
   # and a client following it can still earn a 422. Each such rule stays
-  # visible on its own field, and the conformance spec labels each one
-  # rather than letting it pass as agreement:
+  # visible in the schema (on its own field, or for `finalize` on the rule's
+  # object), and the conformance spec labels each one rather than letting it
+  # pass as agreement:
   #   * a `:json` field's `max_depth:` — `x-permittable-max-depth`;
   #   * a Range of non-numbers (`in: "a".."m"`) — `x-permittable-range`;
   #   * a `validate:` proc — `x-permittable-custom-validation`;
+  #   * a `finalize` block, whose `violate!` cross-field checks no field's
+  #     schema can carry — `x-permittable-finalize` on the rule's object;
+  #   * a `sensitive:` field's `in:` and `format:`, withheld because they
+  #     would publish the secret itself — the same marker (see
+  #     withholds_constraints?);
   #   * a `normalize:` step, which the server runs BEFORE it checks, so
   #     "   " passes a minLength of 3 and is then absent —
   #     `x-permittable-normalize`;
@@ -66,8 +75,16 @@ module Permittable
     # `root:` envelope when the rule declares one. The wrapper itself stays
     # permissive even under `unknown: :error` — the runtime never inspects
     # sibling keys outside the root.
+    #
+    # `finalize` is the one opaque callable that belongs to the rule, not to
+    # a field: it runs once every field has passed and can still refuse the
+    # payload (`ends_on` before `starts_on`), which no per-field keyword can
+    # say. The flag therefore rides on the rule's own object, inside the
+    # `root:` wrapper where the fields are, so a client or generator that
+    # reads the document knows the schema alone is not the whole verdict.
     def rule(permit_rule)
       schema = object(permit_rule[:fields], unknown: permit_rule[:unknown])
+      schema["x-permittable-finalize"] = true if permit_rule[:finalize]
       return schema unless permit_rule[:root]
 
       root = permit_rule[:root].to_s
@@ -125,12 +142,31 @@ module Permittable
     def scalar_schema(field)
       schema = SCALAR_SCHEMAS.fetch(field[:type]).deep_dup
       apply_format_name!(schema, field)
-      apply_in!(schema, field)
+      withheld = withholds_constraints?(field)
+      apply_in!(schema, field) unless withheld
       apply_string_bounds!(schema, field)
-      apply_pattern!(schema, field[:format])
+      apply_pattern!(schema, field[:format]) unless withheld
+      schema["x-permittable-custom-validation"] = true if withheld
       schema
     end
 
+    # A `sensitive:` field's `in:` list/Range and hand-written `format:` ARE
+    # the secret: an enum of the only accepted PINs is an allowlist, and
+    # `pattern: "^FMT_SECRET$"` or a 4000..4999 range names or narrows the
+    # value the same way, so publishing them would defeat the redaction as
+    # surely as publishing a `default:` (see annotate). They are left out,
+    # with `x-permittable-custom-validation` as the only signal, which makes
+    # the exported schema LOOSER than the server for that field. A
+    # `format:` PRESET is the exception: it names a public rule, not a
+    # secret, so it keeps its `format` and `pattern`. `field[:sensitive]` is
+    # already resolved onto a cascaded child, so a child counts. Only a field
+    # that actually declares one of the two is flagged.
+    def withholds_constraints?(field)
+      return false unless field[:sensitive]
+
+      !field[:in].nil? || (!field[:format].nil? && field[:format_name].nil?)
+    end
+
     # A `:json` field's shape is deliberately undeclared, so the schema says
     # "an object" and carries only the bounds the field does declare. JSON
     # Schema has no nesting-depth keyword, so `max_depth:` stays visible as an
@@ -293,17 +329,39 @@ module Permittable
       !allowed.nil? && !allowed.is_a?(Range) && Coercion.in_list(allowed).nil?
     end
 
+    # Every field whose schema admits a string gets its bounds here: :string,
+    # and the string encodings of :decimal, :date and :datetime. minLength
+    # and maxLength only ever constrain the string branch, so the number
+    # branch of a :decimal is untouched. `length:` itself is :string-only.
     def apply_string_bounds!(schema, field)
-      return unless field[:type] == :string
+      return unless Array(schema["type"]).include?("string")
 
       min, max = length_bounds(field[:length])
-      # "" is ABSENT and an absent required field violates, so a required
-      # string can never validly be empty — the schema says so.
-      min = 1 if field[:required] && min.to_i < 1
+      min = 1 if blank_floor?(field) && min.to_i < 1
       schema["minLength"] = min if min
       schema["maxLength"] = max if max
     end
 
+    # "" is ABSENT whatever the type, and an absent required field violates,
+    # so a required field can never validly be "" — the schema says so. For
+    # :date, :datetime and :decimal that is the only thing the schema can say
+    # about a blank: `format` is an annotation, and "decimal" is no format a
+    # validator knows. (A whitespace-only string needs no floor there: those
+    # types refuse it as invalid_type, and the schema never claims to catch a
+    # cast failure. For :date and :datetime `format` at least names the
+    # failure to a validator that asserts it; for :decimal nothing does, so
+    # "   " passes the schema and earns a 422. That is a documented looser
+    # case, the same one as "abc" for a :decimal, and deliberately has no
+    # `pattern` to close it.)
+    #
+    # A nullable field is the exception: it reads "" as an explicit null, a
+    # value rather than an absence, so a floor would reject what the server
+    # takes. A nullable :string keeps the floor it has always had (stricter
+    # than the server, the safe direction); the other types start without.
+    def blank_floor?(field)
+      field[:required] && (field[:type] == :string || !field[:nullable])
+    end
+
     def apply_pattern!(schema, regexp)
       return unless regexp
 
@@ -365,13 +423,18 @@ module Permittable
     # untranslatable or opaque fact in this file is handled: left out, with
     # the `x-permittable-*` extension (here, `writeOnly`/`x-permittable-
     # sensitive`) as the only signal that something is missing.
+    #
+    # The same goes for an array whose elements hold a sensitive field at
+    # any depth (see holds_sensitive?): its `default:`/`example:` carries
+    # that field's value, so it is omitted too.
     def annotate(schema, field)
       decimal_mode = field[:kind] == JSON_TYPE ? :string : :number
-      unless field[:sensitive]
+      unless holds_sensitive?(field)
         schema["default"] = json_value(field[:default], decimal: decimal_mode) if field.key?(:default)
         schema["examples"] = [json_value(field[:example], decimal: decimal_mode)] if field.key?(:example)
       end
-      schema["description"] = field[:desc] if field[:desc]
+      # dup: the stored desc is frozen; the export is editable and detached.
+      schema["description"] = field[:desc].dup if field[:desc]
       if field[:sensitive]
         schema["writeOnly"] = true
         schema["x-permittable-sensitive"] = true
@@ -382,6 +445,30 @@ module Permittable
       schema
     end
 
+    # Is this field sensitive, or does it contain a sensitive field at any
+    # depth? A container's `default:`/`example:` is a whole value, so a
+    # sensitive sub-field's value is inside it. `array :cards, default:
+    # [{}]` with `optional :pan, sensitive: true, default: "4111..."` even
+    # stores `[{"pan" => "4111..."}]`, because the walker fills in each
+    # element's sub-field defaults (see AuthoredValues). Omitting pan's own
+    # default protected nothing while the array still published the value.
+    #
+    # The whole container value is omitted. Redacting only the sensitive
+    # keys inside it was the alternative, and it would mislead. Without the
+    # key, `[{}]` documents a default the server never hands out, since it
+    # fills pan in. An example without its required secret fails the very
+    # items schema it is attached to. A placeholder can fail the
+    # sub-field's own format or in:. The field's own default is omitted
+    # rather than replaced for the same reasons.
+    #
+    # The answer is read off the declaration, not the value, so even
+    # `default: []` is withheld. A value stored as authored (beside a
+    # `transform:`) can key its hashes by String or Symbol, and a check
+    # that has to find the sensitive key there is one more way to miss it.
+    def holds_sensitive?(field)
+      field[:sensitive] || Array(field[:fields]).any? { |child| holds_sensitive?(child) }
+    end
+
     # The server checks the NORMALIZED string, so minLength/maxLength/pattern
     # describe a value the client never sends: under `normalize: :squish`,
     # "   " satisfies a minLength of 3 and then squishes to "" (absent), and

data/lib/permittable/open_api.rb

@@ -188,7 +188,9 @@ module Permittable
       operation = {}
       key = controller_key(controller)
       operation["operationId"] = "#{key.tr('/', '_')}_#{action}" if key && action != "*"
-      operation["description"] = rule[:desc] if rule[:desc]
+      # dup: the stored desc is frozen, and a caller editing the generated
+      # document in place must neither raise nor reach the contract.
+      operation["description"] = rule[:desc].dup if rule[:desc]
       operation["requestBody"] = rule_request_body(rule)
       operation["responses"] = responses_for(rule)
       # The docs must not promise a 422 the server doesn't yet send. Only
@@ -196,6 +198,12 @@ module Permittable
       # Permittable.mode is runtime configuration the export can't see.
       operation["x-permittable-mode"] = "monitor" if rule[:mode] == :monitor
       operation["x-permittable-catch-all"] = true if action == "*"
+      # `finalize` is flagged on the rule's object schema too (see
+      # JsonSchema.rule), but that sits inside the requestBody, and an
+      # operation can end up with no body (every field a path variable) while
+      # finalize still refuses requests. The operation is the one object that
+      # is always there, so the marker rides on it as well.
+      operation["x-permittable-finalize"] = true if rule[:finalize]
       operation
     end
 
@@ -249,15 +257,26 @@ module Permittable
     # once — not counted as an operation colliding with itself. `template`
     # is the route's own spelling when collapse_shapes placed it under
     # another route's, nil otherwise.
+    #
+    # Only OpenAPI's own verbs name a slot. Rails routes any verb in
+    # ActionDispatch::Request::HTTP_METHODS — `via: :report`, `:mkcalendar`,
+    # `:search` and the rest of WebDAV and CalDAV — but a Path Item has fields
+    # for eight, and any other key makes the whole document invalid. A route
+    # on such a verb places nothing; an operation reached by no other route
+    # lands under x-permittable-controllers, as an unrouted one does.
     def route_targets(routes)
       return {} if routes.nil?
 
-      routes.group_by { |route| [route[:controller].to_s, route[:action].to_s] }
+      routes.select { |route| OPENAPI_VERBS.include?(verb_of(route)) }
+            .group_by { |route| [route[:controller].to_s, route[:action].to_s] }
             .transform_values do |matching|
               matching.map { |route| [route[:path], verb_of(route), route[:template]] }.uniq
             end
     end
 
+    # The fixed fields of an OpenAPI 3.1 Path Item that hold an operation.
+    OPENAPI_VERBS = %w[get put post delete options head patch trace].freeze
+
     # OpenAPI forbids two path templates that differ only in their variable
     # names: `/{locale}` and `/{slug}` are one path to it. rails_routes keeps
     # one route's own variants apart, but two routes can still spell one
@@ -665,6 +684,14 @@ module Permittable
     # named in its shadows rather than emitted. Distinct shapes are both
     # kept; OpenAPI allows `/x/new` beside `/x/{a}`.
     #
+    # Before any of that, a variant that is no request path of its own is
+    # dropped (request_path?). An absent group at the start of a route
+    # leaves them: `/(:locale)(/:theme)` without :locale is `//{theme}`,
+    # but Rails squeezes `GET //dark` to `GET /dark`, which binds :locale
+    # (or, constrained away from it, no route at all); and
+    # `(/:locale(/:region))` with nothing present is empty, so the route
+    # does not answer `GET /`.
+    #
     # The list is then reversed, which puts every group's ABSENT variant
     # first at every nesting level, the order the document lists them in.
     # The variants of one route share an operation, and it is the operationId
@@ -689,6 +716,8 @@ module Permittable
 
       kept = {}
       first_of_shape = {}
+      # Such a variant matches no request, so it shadows nothing either.
+      variants = variants.select { |tokens| request_path?(tokens) }
       variants.each_with_index do |tokens, index|
         next if variants.take(index).any? { |earlier| shadowed?(earlier, tokens) }
 
@@ -784,6 +813,16 @@ module Permittable
       path.empty? ? "/" : path
     end
 
+    # Whether a variant could be a request's path. Rails normalizes the
+    # path before it matches any route (Journey::Router::Utils.
+    # normalize_path, from 6.1 to 8.1): it is given a leading "/", and every
+    # run of slashes is squeezed to one. So a variant that does not start
+    # with "/", or that holds two in a row, is matched by no request: the
+    # URL a client would build from it reaches the router as another path.
+    def request_path?(tokens)
+      tokens.first == "/" && tokens.each_cons(2).none? { |pair| pair == %w[/ /] }
+    end
+
     # Whether Rails, trying `earlier` first, leaves `later` no URL: wherever
     # `later` has a token, `earlier` accepts everything it does. Text must be
     # equal; a parameter accepts text its pattern matches whole, and another

data/lib/permittable/railtie.rb

@@ -23,12 +23,99 @@ module Permittable
       # this array in place and ActionDispatch reads the same object per
       # request, so a name registered when a controller loads is seen by the
       # next request. It is the array, not a snapshot, that has to be fed.
+      #
+      # ActiveRecord is a second sink: see FilterAttributesFeed, which also
+      # explains why it is fed here and installed by the initializer below.
+      feed = filter_attributes_feed
       ::Permittable.on_sensitive_parameter do |name|
         filters = app.config.filter_parameters
         filters << name unless filters.include?(name)
+        feed.add(name)
       end
     end
 
+    # AFTER ActiveRecord's own hook, not before: both run when ActiveRecord::Base
+    # loads, in the order they were registered, and that one does
+    # `filter_attributes += config.filter_parameters`. Running first, the feed
+    # would add each name and that copy would add it again as a String (it holds
+    # Strings whenever precompile_filter_parameters is off, as on Rails 6.1).
+    initializer "permittable.filter_attributes",
+                after: "active_record.set_filter_attributes" do
+      feed = filter_attributes_feed
+      ::ActiveSupport.on_load(:active_record) { feed.attach(self) }
+    end
+
+    # The second sink for sensitive names: ActiveRecord::Base.filter_attributes.
+    #
+    # It is a snapshot that never sees a name registered after it loaded. Its
+    # `filter_attributes` is copied from config.filter_parameters exactly once,
+    # when ActiveRecord::Base loads, and in a real app that is BEFORE any
+    # controller registers anything: the first controller's own `model: Person`
+    # loads it. So the copy holds only the proc the initializer appended, which
+    # cannot redact an Integer in the SQL bind log (`[["pin_code", 4321]]`, where
+    # #inspect, handed an already-inspected String, was fine). Each name is
+    # therefore also fed to the model base class directly. The setter drops the
+    # memoized inspection filter, and only names that are missing are added, so
+    # the list holds one entry per name however often a reloaded controller
+    # registers it.
+    #
+    # An app that ASSIGNS `filter_attributes = [...]` (an initializer, or a
+    # to_prepare block, which runs on every reload) rather than appending to it
+    # discards everything fed in so far, and a name that was registered only once
+    # would never come back. So every registration restores EVERY name registered
+    # so far that is missing, not just its own: the next contract to load, or the
+    # next reload re-declaring one, heals the list. (A to_prepare of the gem's own
+    # would not help: railtie blocks run before the app's, so the app's
+    # assignment would still come last.)
+    #
+    # The read-modify-write is done under a lock, as two threads loading
+    # contracts at once would otherwise each write back a list that lacks the
+    # other's name. Nothing inside the lock calls back into the sink or loads
+    # ActiveRecord, so it cannot deadlock.
+    #
+    # ActiveRecord is hooked ONCE for the process, in #attach, rather than once
+    # per name: on_load runs the block at once when ActiveRecord is already
+    # loaded, waits for it otherwise, and never fires in an app without it, where
+    # a hook per registration would queue forever across every code reload.
+    class FilterAttributesFeed
+      def initialize
+        @names = {}
+        @base = nil
+        @lock = Mutex.new
+      end
+
+      # Called with ActiveRecord::Base once it has loaded.
+      def attach(base)
+        @lock.synchronize do
+          @base = base
+          restore
+        end
+      end
+
+      def add(name)
+        @lock.synchronize do
+          @names[name] = true
+          restore if @base
+        end
+      end
+
+      private
+
+      # The caller holds the lock.
+      def restore
+        missing = @names.keys - @base.filter_attributes
+        @base.filter_attributes += missing unless missing.empty?
+      end
+    end
+
+    # Shared by the two initializers, which Rails runs as instance_exec on this
+    # one object. Memoized rather than built in the first, so the second does not
+    # depend on the order Rails settles on for initializers that name no target.
+    def filter_attributes_feed
+      @filter_attributes_feed ||= FilterAttributesFeed.new
+    end
+    private :filter_attributes_feed
+
     rake_tasks do
       load File.expand_path("tasks/openapi.rake", __dir__)
       load File.expand_path("tasks/generate.rake", __dir__)

data/lib/permittable/rspec.rb

@@ -96,7 +96,10 @@ module Permittable
       end
 
       def matching(regexp)
-        @expected[:format] = regexp
+        # `format: "email"` names a preset exactly as `format: :email` does
+        # (see resolve_format!), so the matcher reads a String the same way;
+        # as a Symbol it also reports the preset the same way in a failure.
+        @expected[:format] = regexp.is_a?(String) ? regexp.to_sym : regexp
         self
       end
 
@@ -364,8 +367,9 @@ module Permittable
         "expected the field to be #{expected}, but it is #{actual}" unless actual == expected
       end
 
-      # `matching(:email)` asserts the preset by name, `matching(/re/)` the
-      # Regexp itself.
+      # `matching(:email)` (or `matching("email")`, normalized to a Symbol by
+      # `matching`) asserts the preset by name, `matching(/re/)` the Regexp
+      # itself.
       def format_mismatch(field, expected)
         return option_mismatch(field, :format, expected) unless expected.is_a?(Symbol)
         return if field[:format_name] == expected
@@ -374,7 +378,21 @@ module Permittable
       end
 
       def default_mismatch(field, expected)
-        option_mismatch(field, :default, expected) unless field.key?(:default) && field[:default] == cast_default(field, expected)
+        option_mismatch(field, :default, expected) unless field.key?(:default) && same_default?(field, expected)
+      end
+
+      # A :json default is stored as authored, but the action reads it as
+      # a HashWithIndifferentAccess, String-keyed all the way down. The
+      # declaration's spelling, `with_default(theme: "dark")`, and the
+      # action's, `with_default("theme" => "dark")`, name the same default,
+      # so both sides are read that way before comparing.
+      def same_default?(field, expected)
+        declared = field[:default]
+        if field[:kind] == :json && declared.is_a?(Hash) && expected.is_a?(Hash)
+          ActiveSupport::HashWithIndifferentAccess.new(declared) == ActiveSupport::HashWithIndifferentAccess.new(expected)
+        else
+          declared == cast_default(field, expected)
+        end
       end
 
       # A contract stores its `default:` as the field reads it — cast,
@@ -483,8 +501,11 @@ module Permittable
         end
       end
 
+      # An anonymous controller class has no name, and a Contract instance
+      # never does, so the fallback names the kind of subject it is.
       def subject_name
-        (@subject.respond_to?(:name) && @subject.name) || "the controller"
+        (@subject.respond_to?(:name) && @subject.name) ||
+          (@subject.is_a?(Permittable::Contract) ? "the contract" : "the controller")
       end
 
       def path_label
@@ -616,15 +637,33 @@ module Permittable
           attr_accessor :params
         end
         mirror_contract_unknown_check(host) if @subject.is_a?(Permittable::Contract)
+        action = @action || rule[:actions].first || "call"
+        label_instrumentation(host, action)
         host.permittable_contracts = [rule.merge(mode: :enforce).freeze]
         instance = host.new
         instance.params = @params
-        action = @action || rule[:actions].first || "call"
         violations = instance.permittable_violations(action)
         result = violations.empty? ? instance.permitted_params(action) : nil
         [violations, result]
       end
 
+      # A rejection instruments invalid_parameters.permittable exactly as a
+      # request would. The host is anonymous, so without this the payload
+      # carried controller: nil, action: nil — a subscriber following the
+      # README's shape (`payload[:controller].tr("/", ".")`) raised out of
+      # the matcher. Label it the way the subject itself would: a
+      # controller by its path (or name, or "the contract" when anonymous —
+      # an anonymous controller's controller_path is nil), a Contract as
+      # Contract#call does.
+      def label_instrumentation(host, action)
+        label = if @subject.is_a?(Permittable::Contract) then "Permittable::Contract"
+                elsif @subject.respond_to?(:controller_path) then @subject.controller_path || subject_name
+                else subject_name
+                end
+        host.define_method(:permittable_controller_name) { label }
+        host.define_method(:permittable_action_name) { action }
+      end
+
       # Mirrors Permittable::Contract's own host override verbatim (see
       # lib/permittable/contract.rb): standalone input has no router and no
       # request, so nothing is exempt from unknown: checking, top level or
@@ -666,8 +705,11 @@ module Permittable
         violations.map { |v| v[:code] ? "#{v[:param]} (#{v[:code]})" : v[:param] }.join(", ")
       end
 
+      # An anonymous controller class has no name, and a Contract instance
+      # never does, so the fallback names the kind of subject it is.
       def subject_name
-        (@subject.respond_to?(:name) && @subject.name) || "the contract"
+        (@subject.respond_to?(:name) && @subject.name) ||
+          (@subject.is_a?(Permittable::Contract) ? "the contract" : "the controller")
       end
 
       def action_label

data/lib/permittable/tasks/generate.rake

@@ -4,7 +4,8 @@
 # summary goes to stderr.
 #
 #   bin/rails permittable:generate                      # every uncovered controller not
-#                                                       # left out by Permittable.audit_ignore
+#                                                       # left out by Permittable.audit_ignore,
+#                                                       # for the actions it defines
 #   bin/rails "permittable:generate[UsersController]"   # one controller, even if covered
 namespace :permittable do
   desc "Draft Permittable contracts from models and existing permit calls"
@@ -17,12 +18,13 @@ namespace :permittable do
     controllers = bases.flat_map(&:descendants).uniq.select(&:name)
 
     # { controller => actions to leave out of its draft }. A named controller
-    # is drafted whole, even if covered or ignored; the sweep skips both, and
-    # leaves out what Permittable.audit_ignore names (see Generator.targets).
+    # is drafted even if covered or ignored; the sweep skips both, and leaves
+    # out what Permittable.audit_ignore names. Either leaves out an action the
+    # controller does not define (see Generator.targets and named_target).
     if task_args[:controller]
       controllers = controllers.select { |c| c.name == task_args[:controller] }
       abort "Permittable: no controller named #{task_args[:controller]} was found" if controllers.empty?
-      targets = controllers.to_h { |c| [c, []] }
+      targets = controllers.to_h { |c| [c, Permittable::Generator.named_target(c)] }
     else
       targets = Permittable::Generator.targets(controllers)
     end

data/lib/permittable/version.rb

@@ -1,3 +1,3 @@
 module Permittable
-  VERSION = "0.11.0".freeze
+  VERSION = "0.11.1".freeze
 end