permittable 0.14.0 → 0.15.1

data/lib/permittable/open_api.rb

@@ -197,19 +197,46 @@ module Permittable
     # required field (missing).
     def request_body_for(controller, action)
       rule = controller.permit_rule_for(action)
-      rule && rule_request_body(rule)
+      rule && rule_request_body(rule, controller)
     end
 
-    def rule_request_body(rule)
+    def rule_request_body(rule, controller)
       media_type = body_media_type(rule)
       schema = JsonSchema.rule(rule)
-      schema = form_schema(schema, rule) if media_type == "multipart/form-data"
+      exempt = exempt_keys(controller)
+      schema = form_schema(schema, rule, exempt) if media_type == "multipart/form-data"
+      allow_form_keys!(schema, exempt) if media_type != "multipart/form-data" && rule[:unknown] == :error && !rule[:root]
       {
         "required" => !!(rule[:root] || rule[:fields].any? { |f| f[:required] }),
         "content" => { media_type => { "schema" => schema } }
       }
     end
 
+    # The top-level keys the runtime exempts under `unknown: :error`: the
+    # constant list it subtracts (UNCHECKED_TOP_LEVEL_KEYS) plus the CSRF
+    # parameter the controller renamed, which it reads off the controller too
+    # (permittable_configured_csrf_key). Per-instance overrides and an image
+    # submit's x/y pair cannot be known here.
+    def exempt_keys(controller)
+      token = controller.request_forgery_protection_token if controller.respond_to?(:request_forgery_protection_token)
+      (Permittable::UNCHECKED_TOP_LEVEL_KEYS + [token&.to_s]).compact.uniq
+    end
+
+    # Under `unknown: :error` the runtime still exempts Rails' routing and form
+    # keys (`exempt`, see exempt_keys) at the top of a rootless contract, so a
+    # JSON body carrying `authenticity_token`, `format` or `_method` (a form's
+    # fields sent as JSON, a record echoed back) is accepted, and the body
+    # schema must not forbid it. They
+    # stay in as free, never-required properties, as the multipart body lists
+    # them (see form_schema). A name the contract declares keeps its own
+    # schema. A `root:` rule needs none of this: the keys sit outside the root,
+    # in a wrapper that is permissive already. The plain JsonSchema.rule and
+    # Contract#json_schema describe the contract, not an HTTP body, and a
+    # standalone Contract exempts no form key, so they do not list them.
+    def allow_form_keys!(schema, exempt)
+      exempt.each { |key| schema["properties"][key] ||= {} }
+    end
+
     # A multipart body is not one JSON object: each part is a form field, and
     # Rails reads the part NAMES. `user[avatar]` is the avatar of the `user`
     # hash and a repeated `docs[]` is an array, so the schema's properties
@@ -228,15 +255,15 @@ module Permittable
     # nullable container's null (`user[docs]=""`), the keys of a :json
     # field (`user[extra][any]`), and, for a `root:` rule, any part outside
     # the root, which the runtime never reads; a rootless rule instead gets
-    # the form keys (FORM_KEYS) the runtime exempts at the top level.
-    def form_schema(json_schema, rule)
+    # the keys (`exempt`, see exempt_keys) the runtime exempts at the top level.
+    def form_schema(json_schema, rule, exempt)
       root = rule[:root] && rule[:root].to_s
       form = { properties: {}, patterns: {}, required: [], groups: {}, strict: rule[:unknown] == :error }
       flatten_form(json_schema, [], true, form, skip_group: root)
       if form[:strict] && root
         form[:patterns]["^(?!#{form_escape(root)}(?:\\[|$))"] = {}
       elsif form[:strict]
-        form[:patterns]["^(?:#{Permittable::FORM_KEYS.map { |key| form_escape(key) }.join('|')})$"] = {}
+        form[:patterns]["^(?:#{exempt.map { |key| form_escape(key) }.join('|')})$"] = {}
       end
       schema = { "type" => "object", "properties" => form[:properties] }
       schema["patternProperties"] = form[:patterns] unless form[:patterns].empty?
@@ -386,7 +413,7 @@ module Permittable
       # 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["requestBody"] = rule_request_body(rule, controller)
       operation["responses"] = responses_for(rule)
       # The docs must not promise a 422 the server doesn't yet send. Only
       # the rule's own declaration is contract data — the app-wide
@@ -573,7 +600,7 @@ module Permittable
         else
           free.each do |path, verb, template, defaults|
             holder = (paths[path] ||= {})
-            placed = with_path_parameters(operation, path, controller.permit_rule_for(action), template || path, defaults)
+            placed = with_path_parameters(operation, path, controller.permit_rule_for(action), controller, [template || path, defaults])
             holder[verb] = template ? placed.merge("x-permittable-path" => template) : placed
             slots << OperationSlot.new(holder, verb, verb, operation["operationId"], owner, path)
           end
@@ -692,6 +719,9 @@ module Permittable
     # otherwise: a rootless contract field named like one is that parameter's
     # schema (path_fields), and leaves the body schema.
     #
+    # `route` is `[own, defaults]`; `controller` supplies the keys the body
+    # exempts (see exempt_keys).
+    #
     # `own` is the route's own spelling of the template, which differs
     # from `path` when collapse_shapes placed the route under another
     # route's spelling: the same shape, so the names pair up by position.
@@ -702,7 +732,8 @@ module Permittable
     # not carry them and they are no path parameter. A name the path
     # templates is that parameter instead: `get "o(/:id)", defaults:
     # { id: 5 }` is a parameter on `/o/{id}` and a default only on `/o`.
-    def with_path_parameters(operation, path, rule, own = path, defaults = [])
+    def with_path_parameters(operation, path, rule, controller, route)
+      own, defaults = route
       # A name the path templates twice (a mount and an engine route both
       # name `:id`) is declared once: OpenAPI forbids two parameters with
       # one name and location.
@@ -721,7 +752,7 @@ module Permittable
       operation.each_with_object({}) do |(key, value), out|
         if key == "requestBody"
           out["parameters"] = parameters unless parameters.empty?
-          value = body_without(rule, fields.values + default_fields(rule, supplied), own_names + supplied)
+          value = body_without(rule, controller, fields.values + default_fields(rule, supplied), own_names + supplied)
         end
         out[key] = value unless value.nil?
       end
@@ -782,11 +813,11 @@ module Permittable
     # nothing in the body can make the request wrong. A name the route's
     # `defaults:` fill is treated the same. A rooted contract
     # needs none of this: its wrapper object is permissive already.
-    def body_without(rule, moved, templated)
+    def body_without(rule, controller, moved, templated)
       rest = rule[:fields] - moved
       return if rest.empty? && !moved.empty?
 
-      body = rule_request_body(moved.empty? ? rule : rule.merge(fields: rest))
+      body = rule_request_body(moved.empty? ? rule : rule.merge(fields: rest), controller)
       return body unless rule[:unknown] == :error && !rule[:root]
 
       properties = body["content"].values.first["schema"]["properties"]
@@ -1013,13 +1044,15 @@ module Permittable
     # The names a route fills from its `defaults:` (`scope`, `resources` and
     # `mount` take them too), as strings. The router puts them into
     # path_parameters beside the URL's own, so the client cannot set them;
-    # `controller`, `action` and `format` are the router's own keys and
-    # are left out, as the runtime leaves them out of `unknown:`. A
+    # `controller` and `action` are the router's own keys and are left
+    # out, as the runtime leaves them out of `unknown:`. `format` is left in:
+    # a `defaults: { format: ... }` lands in path_parameters like any other
+    # default, so a contract field of that name is filled by it. A
     # hand-built route that cannot say fills nothing.
     def route_defaults(route)
       return [] unless route.respond_to?(:defaults)
 
-      route.defaults.keys.map(&:to_s) - %w[controller action format]
+      route.defaults.keys.map(&:to_s) - %w[controller action]
     end
 
     # The Prefix of each variant of a mount's path under each of `prefixes`,

data/lib/permittable/rspec.rb

@@ -469,6 +469,8 @@ module Permittable
       end
 
       def cast_json_default(field, expected)
+        # Absent on a nullable field is the nil a contract stores for it.
+        return nil if field[:nullable] && Coercion.absent_value?(expected)
         return expected unless expected.is_a?(Hash)
 
         status, value = AuthoredValues.read_json(field, expected)
@@ -634,7 +636,7 @@ module Permittable
       # `not_to ...returning(x)` would pass both on a rejection and on an
       # acceptance returning anything else.
       def does_not_match?(subject) # rubocop:disable Naming/PredicatePrefix -- the RSpec protocol name
-        raise ArgumentError, negated_qualifier_message if @returning || !@expected_violations.empty?
+        raise ArgumentError, negated_qualifier_message(subject) if @returning || !@expected_violations.empty?
 
         rule = locate(subject)
         return false unless rule
@@ -649,9 +651,12 @@ module Permittable
         if @expect_accepted
           return "expected #{subject_name} to #{description}, but it rejected them: #{summary(@violations)}" unless @violations.empty?
 
-          "expected #{subject_name} to #{description}, but it accepted them but returned #{@result.to_h.inspect}"
+          "expected #{subject_name} to #{description}, but it accepted them but returned " \
+            "#{printable(@result.to_h)}#{differs_note}"
         else
-          return "expected #{subject_name} to #{description}, but it accepted them, returning #{@result.to_h.inspect}" if @violations.empty?
+          if @violations.empty?
+            return "expected #{subject_name} to #{description}, but it accepted them, returning #{printable(@result.to_h)}"
+          end
 
           "expected #{subject_name} to #{description}, but the violations were: #{summary(@violations)}"
         end
@@ -668,7 +673,7 @@ module Permittable
         label = @expect_accepted ? "accept those params" : "reject those params"
         label += action_label
         label += " with #{summary(@expected_violations)}" unless @expected_violations.empty?
-        label += " returning #{@returning.inspect}" if @returning
+        label += " returning #{printable(@returning)}" if @returning
         label
       end
 
@@ -682,15 +687,27 @@ module Permittable
       # first so a matcher object reused across examples (or re-chained
       # with another for_action) never reports a previous run's problem.
       def locate(subject)
-        @problem = @violations = @result = nil
+        @problem = @violations = @result = @root = nil
         @subject = resolve_subject(subject)
-        resolve_rule
-      end
-
-      def negated_qualifier_message
+        rule = resolve_rule
+        @root = rule[:root] if rule
+        rule
+      end
+
+      def negated_qualifier_message(subject = nil)
+        # Raised before the rule is located, so the root a scoped filter
+        # needs is looked up here, best effort: a subject or an ambiguity
+        # that locate would refuse (a BasicObject answers no respond_to?) is not
+        # this message's to report, and leaves the filter unscoped (the
+        # shallow one) rather than masking the qualifier error.
+        begin
+          locate(subject) if subject
+        rescue StandardError
+          @root = nil
+        end
         call = @expect_accepted ? "accept_params" : "reject_params"
         qualifiers = []
-        qualifiers << "returning #{@returning.inspect}" if @returning
+        qualifiers << "returning #{printable(@returning)}" if @returning
         qualifiers << "with_violation #{summary(@expected_violations)}" unless @expected_violations.empty?
         "#{LABEL}: `not_to #{call}(...)` cannot take qualifiers (here: #{qualifiers.join(', ')}) — " \
           "negating one is ambiguous, since it would pass both when the params are " \
@@ -788,36 +805,40 @@ module Permittable
       # payload belongs to the spec. The copy stringifies Symbol keys, which
       # the normalizer's HashWithIndifferentAccess does anyway but only after
       # it has read a Symbol :tempfile key as an upload, a key a request
-      # (String keys only) never has. A Parameters payload is unwrapped first
-      # so it is normalized like the Hash it wraps.
+      # (String keys only) never has, and Symbol values (see copy_payload).
+      # A Parameters payload is unwrapped first so it is normalized like the
+      # Hash it wraps. Without actionpack's request code only the normalizer
+      # is skipped; the copy (and its Symbol stringifying) still happens.
       def request_params
+        payload = copy_payload(@params.respond_to?(:to_unsafe_h) ? @params.to_unsafe_h : @params)
         utils = request_utils
-        return @params unless utils
-
-        payload = @params.respond_to?(:to_unsafe_h) ? @params.to_unsafe_h : @params
-        utils.normalize_encode_params(copy_payload(payload))
+        utils ? utils.normalize_encode_params(payload) : payload
       end
 
       # Rails main moved the class from ActionDispatch::Request::Utils to
-      # ActionDispatch::Http::Utils. nil only when ActionDispatch is not
-      # loaded at all (a non-Rails stand-in controller); once it is, a rename
-      # this does not know raises instead of silently skipping the
-      # normalization, which would bring the false greens back.
+      # ActionDispatch::Http::Utils. nil when actionpack's request code is not
+      # loaded (a non-Rails stand-in controller, or a bare ActionDispatch module
+      # that something else namespaced): there is nothing to normalize with, and
+      # nothing was renamed. Once ActionDispatch::Request exists, a rename this
+      # does not know raises instead of silently skipping the normalization,
+      # which would bring the false greens back.
       def request_utils
-        return unless defined?(ActionDispatch)
-
         if defined?(ActionDispatch::Http::Utils) then ActionDispatch::Http::Utils
         elsif defined?(ActionDispatch::Request::Utils) then ActionDispatch::Request::Utils
-        else
+        elsif defined?(ActionDispatch::Request)
           raise "Permittable's matchers cannot find Rails' parameter normalizer: neither " \
                 "ActionDispatch::Http::Utils nor ActionDispatch::Request::Utils is defined"
         end
       end
 
+      # Symbol keys become Strings, and so do Symbol values: a request carries
+      # every scalar as a String (or a JSON number, boolean or null), never a
+      # Symbol, so `status: :active` is the "active" the contract would read.
       def copy_payload(value)
         case value
         when Hash then value.to_h { |key, item| [key.is_a?(Symbol) ? key.to_s : key, copy_payload(item)] }
         when Array then value.map { |item| copy_payload(item) }
+        when Symbol then value.to_s
         else value
         end
       end
@@ -874,6 +895,116 @@ module Permittable
         raise ArgumentError, "#{LABEL}: the subject of accept_params/reject_params must include Permittable (got #{subject.inspect})"
       end
 
+      # A hash echoed into a failure message, which lands in CI logs, goes out
+      # redacted the way a request log is: by the names `sensitive:` fields
+      # registered, and by the app's config.filter_parameters when a Rails
+      # application is booted. Only the printed copy is filtered; the matching
+      # itself reads the real values.
+      def printable(hash)
+        redacted(hash).inspect
+      end
+
+      # The redacted structure itself, which differs_note walks beside the
+      # real one. A rule with a root: has its hash put back under that root
+      # for the app's filter, as a request logs it, so a scoped filter
+      # ("payment.number", /\Apayment\.code\z/) matches; the registry pass
+      # runs on the hash alone, as it does at runtime.
+      def redacted(hash)
+        inner = redact_sensitive(hash)
+        filter = parameter_filter
+        return inner unless filter
+        return filter.filter(inner) unless @root
+
+        key = @root.to_s
+        filter.filter(key => inner)[key]
+      end
+
+      # The registry's names, by whatever it can answer: #include?, else its
+      # #names matched the way the registry matches (case-insensitive
+      # substring). One with neither is left to its #to_proc in
+      # parameter_filter. A masked value is replaced whole, a Hash included.
+      # An ActionController::Parameters is unwrapped, so its nested values
+      # are reached too.
+      def redact_sensitive(value)
+        value = value.to_unsafe_h if value.respond_to?(:to_unsafe_h)
+        return value.map { |item| redact_sensitive(item) } if value.is_a?(Array)
+        return value unless value.is_a?(Hash)
+
+        registry = Permittable.filter_parameter_registry
+        value.to_h do |key, item|
+          [key, sensitive_name?(registry, key) ? Permittable::FilterParameterRegistry::FILTERED : redact_sensitive(item)]
+        end
+      end
+
+      def sensitive_name?(registry, key)
+        if registry.respond_to?(:include?)
+          registry.include?(key)
+        elsif registry.respond_to?(:names)
+          name = key.to_s.downcase
+          registry.names.any? { |sensitive| name.include?(sensitive.to_s.downcase) }
+        else
+          false
+        end
+      end
+
+      # Rails' ParameterFilter over the app's config.filter_parameters, plus
+      # the registry's own #to_proc when it can answer neither #include? nor
+      # #names (a proc masks only Strings, but it is all such a registry
+      # offers). ActiveSupport::ParameterFilter is not loaded by
+      # `require "active_support"` before 7.0, and a Rails 6.1 app without
+      # ActionDispatch::Request has not loaded it either; it has been
+      # requirable since 6.0.
+      def parameter_filter
+        filters = []
+        app = defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+        filters.concat(Array(app.config.filter_parameters)) if app
+        registry = Permittable.filter_parameter_registry
+        filters << registry.to_proc unless registry.respond_to?(:include?) || registry.respond_to?(:names)
+        return if filters.empty?
+
+        begin
+          require "active_support/parameter_filter"
+        rescue LoadError
+          return
+        end
+        ActiveSupport::ParameterFilter.new(filters)
+      end
+
+      # The registry matches by substring, like Rails (`pin` also redacts
+      # `shipping`), so an expected and an actual hash that differ only under
+      # redacted names print the same. Say where they differ, by name only.
+      def differs_note
+        return "" unless @returning
+
+        expected = ActiveSupport::HashWithIndifferentAccess.new(@returning).to_h
+        actual = @result.to_h
+        return "" if expected == actual || printable(expected) != printable(actual)
+
+        # A filter on the root itself masks the whole hash, leaving the root as the one path.
+        paths = differing_paths(expected, actual, redacted(expected), redacted(actual)).map { |path| path || @root.to_s }
+        paths.empty? ? "" : "; differs at: #{paths.join(', ')}"
+      end
+
+      # Walks the real hashes beside their redacted copies and stops at the
+      # redaction boundary: a node the copy shows as masked is named by its
+      # path alone when the real values differ, and not entered, since a key
+      # or an index below it is as secret as its value.
+      def differing_paths(expected, actual, expected_masked, actual_masked, prefix = nil)
+        filtered = Permittable::FilterParameterRegistry::FILTERED
+        masked = expected_masked == filtered || actual_masked == filtered
+        if !masked && expected.is_a?(Hash) && actual.is_a?(Hash)
+          (expected.keys | actual.keys).flat_map do |key|
+            differing_paths(expected[key], actual[key], expected_masked[key], actual_masked[key], [prefix, key].compact.join("."))
+          end
+        elsif !masked && expected.is_a?(Array) && actual.is_a?(Array) && expected.length == actual.length
+          expected.each_index.flat_map do |i|
+            differing_paths(expected[i], actual[i], expected_masked[i], actual_masked[i], "#{prefix}[#{i}]")
+          end
+        else
+          expected == actual ? [] : [prefix]
+        end
+      end
+
       def summary(violations)
         violations.map { |v| v[:code] ? "#{v[:param]} (#{v[:code]})" : v[:param] }.join(", ")
       end

data/lib/permittable/tasks/audit.rake

@@ -13,9 +13,10 @@ namespace :permittable do
 
     # Every controller, not just the ones including Permittable — a controller
     # that never included it is unguarded, which is exactly the finding. Bare
-    # ActionController::Metal ones included; see Audit.rails_controllers.
-    controllers = Permittable::Audit.rails_controllers
+    # ActionController::Metal ones included, and autoloaded framework ones
+    # (Rails::HealthController) the routes name; see Audit.rails_controllers.
     routes = Permittable::OpenAPI.rails_routes(Rails.application)
+    controllers = Permittable::Audit.rails_controllers(routes)
 
     entries = Permittable::Audit.entries(controllers: controllers, routes: routes)
     stale = Permittable::Audit.stale(controllers: controllers, routes: routes)

data/lib/permittable/version.rb

@@ -1,3 +1,3 @@
 module Permittable
-  VERSION = "0.14.0".freeze
+  VERSION = "0.15.1".freeze
 end