permittable 0.8.0 → 0.10.0

data/lib/permittable/audit.rb

@@ -0,0 +1,268 @@
+require "permittable/open_api"
+
+module Permittable
+  # Contract COVERAGE — the fourth reader of the registry, and the one that
+  # answers a question none of the others can: what is *not* covered?
+  #
+  # A controller declaring `permit_params :create` looks adopted. If it also
+  # answers PATCH, that action is validating nothing, and nothing in the gem
+  # said so — the generator only notices controllers with no contract at all,
+  # and the OpenAPI exporter documents what exists rather than what is
+  # missing. The audit crosses the registry with the ROUTE SET, so a
+  # half-covered controller is as visible as an uncovered one.
+  #
+  #   bin/rails permittable:audit           # the table, plus a summary
+  #   bin/rails permittable:audit[strict]   # ...and exit 1 if a write action
+  #                                         #    is unguarded (a CI gate)
+  #
+  # Plain Ruby over the frozen registry and a list of route descriptors (the
+  # same `{ controller:, action:, verb:, path: }` shape OpenAPI.rails_routes
+  # produces, plus the optional `route:` it tags each one with), so it is
+  # unit-testable without Rails. Unlike the exporter it
+  # reports the EFFECTIVE mode: an audit runs inside the app that sets
+  # `Permittable.mode`, so it can resolve what the exporter deliberately
+  # cannot.
+  module Audit
+    module_function
+
+    # Verbs that carry a request body — the ones where "no contract" means
+    # untrusted input reaching the action unchecked. A GET without a contract
+    # is usually fine; a POST without one is the finding.
+    BODY_VERBS = %w[post put patch].freeze
+
+    # One routed action, paired with the rule a request for it would resolve
+    # through (nil when nothing covers it — including when the controller
+    # never included the concern, which is exactly the case worth finding).
+    #
+    # `missing_action` marks a route to an action the controller does not
+    # define — see Audit.missing_action?. `route` identifies the route the
+    # path came from (nil for a hand-built descriptor, which is then its own
+    # route); see `summary`.
+    Entry = Struct.new(:controller, :action, :verb, :path, :rule, :missing_action, :route, keyword_init: true) do
+      def covered?
+        !rule.nil?
+      end
+
+      def missing_action?
+        missing_action == true
+      end
+
+      # The mode this action would actually run in, rule-level declaration
+      # first and the app-wide default behind it.
+      def mode
+        rule && (rule[:mode] || Permittable.mode)
+      end
+
+      def model
+        rule && rule[:model]
+      end
+
+      def unknown
+        rule && rule[:unknown]
+      end
+
+      def body?
+        BODY_VERBS.include?(verb.to_s.downcase)
+      end
+    end
+
+    # Every routed action of every given controller, sorted for stable output.
+    # Pass ALL controllers, not just the ones including Permittable — a
+    # controller that never included it is unguarded, which is the point.
+    def entries(controllers:, routes:)
+      routes = routes.to_a
+      controllers.flat_map { |controller| controller_entries(controller, routes) }
+                 .sort_by { |entry| [entry.controller, entry.path, entry.verb.to_s] }
+    end
+
+    def controller_entries(controller, routes)
+      key = OpenAPI.controller_key(controller) || controller.inspect
+      missing = missing_lookup(controller)
+      routes.select { |route| route[:controller].to_s == key }.map do |route|
+        action = route[:action].to_s
+        Entry.new(controller: key, action: action, verb: route[:verb], path: route[:path],
+                  rule: rule_for(controller, action), missing_action: missing[action],
+                  route: route[:route])
+      end
+    end
+
+    # action => missing?, answered once per action: a `via: :all` route is
+    # five entries for one action, and each resolver call builds a controller.
+    # The action list is read once per controller, not once per route.
+    def missing_lookup(controller)
+      listed = listed_actions(controller)
+      Hash.new { |memo, action| memo[action] = missing_action?(controller, action, listed) }
+    end
+
+    # Normalised like OpenAPI.documented_actions: a duck listing Symbols would
+    # otherwise be missing every action, and strict would pass everything.
+    # nil when the controller cannot list its actions.
+    def listed_actions(controller)
+      controller.action_methods.to_set(&:to_s) if controller.respond_to?(:action_methods)
+    end
+
+    # `resources :posts` routes all seven actions whether or not the
+    # controller defines them, and Rails 404s the ones it does not — so an
+    # undefined `create` is no unguarded input, and failing a strict run over
+    # it was a false positive. Labelled rather than dropped, so the reader
+    # still sees the route. A controller that cannot list its actions is
+    # assumed to have them all.
+    def missing_action?(controller, action, listed = listed_actions(controller))
+      return false if listed.nil? || listed.include?(action)
+
+      !dispatchable?(controller, action)
+    end
+
+    # action_methods is not all Rails dispatches: an `action_missing` handler
+    # takes every unlisted action, and ImplicitRender renders a template with
+    # no method behind it — both with the body parsed, so both are input.
+    # Rather than re-derive that, ask Rails's own resolver: method_for_action
+    # is nil exactly when dispatch would raise ActionNotFound (the same
+    # private method, unchanged from 6.1 to 8.1). It needs no request. A
+    # plain-Ruby duck has no resolver, so its action list is the answer; a
+    # resolver that raises is inconclusive, so assume the action exists: for
+    # a gate, a false alarm beats a missed endpoint.
+    def dispatchable?(controller, action)
+      return false unless controller.is_a?(Class) &&
+                          (controller.method_defined?(:method_for_action) ||
+                           controller.private_method_defined?(:method_for_action))
+
+      begin
+        !controller.new.send(:method_for_action, action).nil?
+      rescue StandardError
+        true
+      end
+    end
+
+    def rule_for(controller, action)
+      controller.respond_to?(:permit_rule_for) ? controller.permit_rule_for(action) : nil
+    end
+
+    # { controller => [action, ...] } for contracts declared against actions
+    # no route reaches, or that a route reaches but Rails would 404 — either
+    # way a renamed or deleted action leaving its contract behind. The second
+    # kind is in no summary bucket, so without this it would vanish from the
+    # report's conclusions. Catch-all rules declare no actions, so they never
+    # appear here.
+    def stale(controllers:, routes:)
+      routes = routes.to_a
+      controllers.each_with_object({}) do |controller, found|
+        next unless controller.respond_to?(:permittable_contracts)
+
+        key = OpenAPI.controller_key(controller) || controller.inspect
+        routed = routes.select { |route| route[:controller].to_s == key }.map { |route| route[:action].to_s }
+        declared = controller.permittable_contracts.flat_map { |rule| rule[:actions] }.uniq
+        missing = missing_lookup(controller)
+        left = declared.select { |action| !routed.include?(action) || missing[action] }
+        found[key] = left unless left.empty?
+      end
+    end
+
+    # The numbers worth putting in a CI log. `uncovered_with_body` is the one
+    # that should be zero; `unguarded_models` counts covered actions whose
+    # rule declares no `model:`, so no schema-drift guard runs for them.
+    #
+    # Counted per route and verb rather than per row: `scope "(:locale)"`
+    # expands one route into two paths, both listed in the table, and one
+    # unguarded POST must not count as two. Only a route's OWN variants
+    # collapse — `post "/users"` and `post "/admin/users"` are two ways into
+    # users#create, two gaps if neither is covered, and `[strict]` must see
+    # both.
+    #
+    # An action the controller does not define takes no body, and a contract
+    # left on one guards nothing, so it is counted as `missing_actions` and in
+    # no other bucket — the buckets stay disjoint and still add up to `actions`.
+    def summary(entries)
+      entries = routed(entries)
+      found, missing = entries.partition { |e| !e.missing_action? }
+      {
+        actions: entries.length,
+        enforced: found.count { |e| e.mode == :enforce },
+        monitored: found.count { |e| e.mode == :monitor },
+        uncovered: found.count { |e| !e.covered? },
+        uncovered_with_body: found.count { |e| !e.covered? && e.body? },
+        unguarded_models: found.count { |e| e.covered? && e.model.nil? },
+        missing_actions: missing.length
+      }
+    end
+
+    # One entry per route and verb, in the entries' own order. `route` is a
+    # position within ONE rails_routes call, so it is keyed with the
+    # controller and action: an app's list concatenated with an engine's
+    # reuses the same small integers for unrelated routes. An entry with no
+    # `route` (a hand-built descriptor) is its own route.
+    def routed(entries)
+      entries.uniq { |e| e.route.nil? ? e.object_id : [e.controller, e.action, e.route, e.verb.to_s.downcase] }
+    end
+
+    # The human-readable report: one block per controller, then the summary,
+    # then anything stale.
+    def format(entries, stale: {})
+      return "Permittable audit: no routed actions to report.\n" if entries.empty?
+
+      out = entries.group_by(&:controller).map { |key, group| controller_block(key, group) }
+      out << summary_lines(summary(entries), rows: entries.length)
+      out << stale_lines(stale) unless stale.empty?
+      "#{out.join("\n")}\n"
+    end
+
+    def controller_block(key, group)
+      rows = group.map do |entry|
+        "  #{entry.verb.to_s.upcase.ljust(6)} #{entry.path.ljust(34)} #{entry.action.ljust(12)} #{status(entry)}"
+      end
+      "#{key}\n#{rows.join("\n")}"
+    end
+
+    # A covered action reads as its effective mode; an uncovered one says so,
+    # and says whether that matters (a body-carrying verb with no contract is
+    # unvalidated input, not just a gap in the table). A route to an action
+    # the controller does not define says that instead of claiming a body.
+    def status(entry)
+      return ["no contract", uncovered_note(entry)].compact.join(" — ") unless entry.covered?
+
+      parts = [entry.mode.to_s]
+      parts << "model: #{entry.model.name}" if entry.model.respond_to?(:name) && entry.model.name
+      parts << "unknown: #{entry.unknown}" unless entry.unknown == :ignore
+      parts << not_found_note(entry)
+      parts.compact.join("  ")
+    end
+
+    def uncovered_note(entry)
+      not_found_note(entry) || ("ACCEPTS A BODY" if entry.body?)
+    end
+
+    # The one wording for a route Rails would 404, covered or not.
+    def not_found_note(entry)
+      "action not found" if entry.missing_action?
+    end
+
+    # The table lists rows (a verb on a path) and the summary counts routes;
+    # when the two numbers differ, the line gives both and names each. Rows,
+    # not distinct paths: PATCH and PUT on one path are two rows. It does not
+    # say WHY they differ: an optional segment's variants are the usual
+    # reason, but two concatenated route lists sharing a controller, action
+    # and index collapse the same way.
+    def summary_lines(counts, rows: counts[:actions])
+      body = counts[:uncovered_with_body]
+      missing = counts[:missing_actions]
+      # Its own bucket, so the head line still adds up to the route count.
+      not_found = ", #{missing} not found (Rails 404s #{missing == 1 ? 'it' : 'them'})" unless missing.zero?
+      listed = " in #{rows} rows" unless rows == counts[:actions]
+      [
+        "",
+        "#{counts[:actions]} routed action#{'s' unless counts[:actions] == 1}#{listed}: " \
+        "#{counts[:enforced]} enforced, #{counts[:monitored]} in monitor mode, " \
+        "#{counts[:uncovered]} without a contract#{not_found}",
+        "  #{body} of those accept a request body#{' — untrusted input reaches the action unchecked' unless body.zero?}",
+        "  #{counts[:unguarded_models]} covered action#{'s' unless counts[:unguarded_models] == 1} " \
+        "declare no model:, so no schema-drift guard runs for them"
+      ].join("\n")
+    end
+
+    def stale_lines(stale)
+      pairs = stale.flat_map { |key, actions| actions.map { |action| "#{key}##{action}" } }
+      "\nContracts declared for actions no route reaches or Rails would 404 (renamed or deleted?):\n" \
+        "#{pairs.map { |pair| "  #{pair}" }.join("\n")}"
+    end
+  end
+end

data/lib/permittable/authored_values.rb

@@ -0,0 +1,63 @@
+module Permittable
+  # The request walker, pointed at an authored array `default:`/`example:`
+  # at class load — the same permittable_check_array a request goes
+  # through, so the two cannot drift apart. Two seams are overridden:
+  #
+  #   * the field WHOSE default:/example: is being validated does not run
+  #     its own `transform:` — see permittable_transform below for exactly
+  #     which field that is and why. A SUB-FIELD's own transform: still
+  #     runs, so what gets stored is what an equivalent request would
+  #     produce.
+  #   * violations carry no `message:` — they become an ArgumentError for
+  #     the contract's author, not a response for a client, and I18n may not
+  #     be loaded yet.
+  class AuthoredValues
+    include Permittable
+
+    def self.read_array(field, value)
+      new.read_array(field, value)
+    end
+
+    def self.summary(violations)
+      new.summary(violations)
+    end
+
+    # [value as a request would get it, violations]
+    def read_array(field, value)
+      violations = []
+      @field = field
+      read = permittable_check_array(field, value, path: field[:name].to_s, unknown: :ignore, violations: violations)
+      [read, violations]
+    end
+
+    def summary(violations)
+      permittable_violation_summary(violations)
+    end
+
+    private
+
+    # Suppresses transform: for the field WHOSE default/example is being
+    # authored-validated (@field, compared by identity) — never for a
+    # sub-field nested inside it. A sub-field's own transform: is app code
+    # too, but it belongs to a DIFFERENT field's contract: an equivalent
+    # request sending that sub-field's value would run it, so the stored
+    # default has to match, or an omitted field and an explicitly-sent
+    # identical value silently diverge (and the exported OpenAPI default,
+    # which reads this same value, documents one the server never produces).
+    #
+    # When @field itself has a transform:, its result is discarded anyway
+    # (validate_array_authored_value! stores the value AS AUTHORED instead —
+    # see its comment), so nothing inside its subtree is worth reading
+    # transformed: suppressing every nested call too keeps that walk free of
+    # app code, exactly as a scalar default's cast-only check already is.
+    def permittable_transform(field, value)
+      return value if @field[:transform] || field.equal?(@field)
+
+      super
+    end
+
+    def permittable_violation(_field, param, code)
+      { param: param, code: code.to_s }
+    end
+  end
+end

data/lib/permittable/column_guard.rb

@@ -10,24 +10,151 @@ module Permittable
   # (NameError from a typo etc.) keep surfacing. Skipping is self-healing:
   # once the migration runs and classes reload, validation happens for real.
   module ColumnGuard
+    # Column types that mean the same thing for a contract's purposes, grouped
+    # so the check can catch a column RETYPED out from under a contract
+    # without second-guessing a declaration that merely differs in flavour.
+    #
+    # The numeric group deliberately includes :boolean — a boolean stored as
+    # an integer 0/1 is a real legacy pattern, and ActiveRecord casts cleanly
+    # between all of them. The temporal group is one group for the same
+    # reason: a :date contract on a datetime column is a narrowing, not drift.
+    #
+    # Anything absent here — :json, :jsonb, :binary, an adapter's own :inet or
+    # :money — is NOT checked. A contract has no faithful type for those, so
+    # whatever an app improvised is left alone rather than guessed about.
+    TYPE_GROUPS = {
+      string: :text, text: :text, citext: :text, uuid: :text, enum: :text, char: :text,
+      integer: :numeric, bigint: :numeric, float: :numeric, decimal: :numeric, boolean: :numeric,
+      date: :temporal, datetime: :temporal, time: :temporal, timestamp: :temporal, timestamptz: :temporal
+    }.freeze
+
     module_function
 
     # `types:` teaches the error message: a Symbol/String applies to every
     # listed field, a Hash maps field => type. The raised ArgumentError then
-    # appends a ready-to-paste migration command.
-    def ensure_columns_on!(label, klass, *fields, types: nil)
+    # appends a ready-to-paste migration command. `allowed:` maps field =>
+    # its `in:`, for the fields that declare one; only the enum rule reads it.
+    def ensure_columns_on!(label, klass, *fields, types: nil, check_types: false, allowed: nil)
       return false unless schema_reachable?(klass)
 
       fields.flatten.compact.each do |field|
-        next if klass.column_names.include?(field.to_s)
+        unless klass.column_names.include?(field.to_s)
+          raise ArgumentError,
+                "#{label}: '#{field}' does not exist in the database (table: #{klass.table_name})." \
+                "#{column_migration_hint(klass, field, types)}"
+        end
 
-        raise ArgumentError,
-              "#{label}: '#{field}' does not exist in the database (table: #{klass.table_name})." \
-              "#{column_migration_hint(klass, field, types)}"
+        ensure_column_type!(label, klass, field, types, allowed) if check_types
       end
       true
     end
 
+    # The type half of the drift guard, opt-in via Permittable
+    # .check_column_types. It compares GROUPS rather than exact types (see
+    # TYPE_GROUPS) and stays silent unless both sides are known, so it can
+    # only fire on a genuine cross-family mismatch — a contract still saying
+    # :datetime after the column became a string, say.
+    def ensure_column_type!(label, klass, field, types, allowed = nil)
+      declared = types.is_a?(Hash) ? types[field.to_sym] : types
+      column = klass.columns_hash[field.to_s]
+      return unless declared && column
+
+      wanted = TYPE_GROUPS[declared.to_sym]
+      enum = enum_attribute?(klass, field)
+      # Checked before the column's type, which an enum's contract does not
+      # depend on: see ensure_enum_contract!.
+      return ensure_enum_contract!(label, klass, field, declared, allowed && allowed[field.to_sym]) if enum && wanted == :text
+
+      # `column.type` is nil for a SQL type the adapter does not recognise
+      # (a PostGIS geometry column without the extension loaded, a custom
+      # domain type). That is exactly the "no faithful contract type" case
+      # this guard documents staying silent for — not a reason to raise
+      # NoMethodError out of a controller's class body.
+      return unless column.type
+
+      actual = TYPE_GROUPS[column.type.to_sym]
+      return if wanted.nil? || actual.nil? || wanted == actual
+
+      # On an enum, `virtual: true` would be the wrong advice: it switches
+      # off the existence check too, and the field IS backed by this column.
+      fix = if enum
+              "'#{field}' is an enum on #{model_expr(klass)}: declare it :string, in: #{enum_keys_expr(klass, field)}."
+            else
+              "Change the contract to match the column, migrate the column to match the contract, " \
+                "or declare the field virtual: true if it is not backed by this column."
+            end
+      raise ArgumentError,
+            "#{label}: '#{field}' is declared :#{declared} but the column is :#{column.type} " \
+            "(table: #{klass.table_name}). #{fix}"
+    end
+
+    # `model:` is only duck-typed on column_names, hence the respond_to?.
+    def enum_attribute?(klass, field)
+      klass.respond_to?(:defined_enums) && klass.defined_enums.key?(field.to_s)
+    end
+
+    # A Rails enum is submitted by its NAME — `status: "shipped"` — whatever
+    # the column stores, so a text declaration is the right contract for any
+    # enum, integer-backed included, and is not held to the column's group.
+    # The price of that exemption is an `in:` naming what the enum accepts:
+    # assignment raises ArgumentError for anything else, so without one
+    # `status: "bogus"` passes the contract and becomes a 500 in the action.
+    # A string-backed enum is held to the same rule even though its column
+    # group already matched — the 500 is identical. Any other declaration on
+    # an enum is still held to the column's own group (`:integer` on an
+    # integer-backed enum passes, `:datetime` does not).
+    #
+    # Accepted means what the enum's cast accepts: every name, plus every
+    # stored value that is a String (a string-backed enum takes `"p"` for
+    # `pro:` as readily as `"pro"`). An integer-backed enum's stored values
+    # are not accepted — a request carries `"0"`, which maps to nothing. A
+    # Range, or anything else without a finite list, cannot be checked, so it
+    # is refused rather than trusted.
+    #
+    # Only `enum` is recognised. The attribute API (`attribute :x, :datetime`
+    # over a string column) is left compared against the column by choice:
+    # an enum's mapping says exactly which strings are valid, an attribute
+    # override says nothing a contract could be checked against.
+    def ensure_enum_contract!(label, klass, field, declared, listed)
+      problem =
+        if listed.nil?
+          "declared :#{declared} without an in:"
+        elsif listed.is_a?(Range) || !listed.respond_to?(:to_a)
+          "declared :#{declared} with an in: that does not list its values"
+        else
+          stray = listed.to_a - enum_values(klass, field)
+          return if stray.empty?
+
+          "declared :#{declared} with an in: listing values it would refuse: #{stray.map(&:inspect).join(', ')}"
+        end
+
+      raise ArgumentError,
+            "#{label}: '#{field}' is an enum on #{model_expr(klass)}, #{problem} (table: #{klass.table_name}). " \
+            "A value outside the enum would pass the contract and then raise on assignment. " \
+            "Declare it with in: #{enum_keys_expr(klass, field)}."
+    end
+
+    def enum_values(klass, field)
+      mapping = klass.defined_enums[field.to_s]
+      mapping.keys.map(&:to_s) + mapping.values.grep(String)
+    end
+
+    # `Order.statuses.keys` when the enum's plural reader exists, and the
+    # always-valid `defined_enums["..."]` spelling when it does not (a name
+    # that is not a Ruby identifier, a duck-typed model).
+    def enum_keys_expr(klass, field)
+      reader = field.to_s.pluralize
+      if reader.match?(/\A[a-z_][a-zA-Z0-9_]*\z/) && klass.respond_to?(reader)
+        "#{model_expr(klass)}.#{reader}.keys"
+      else
+        "#{model_expr(klass)}.defined_enums[#{field.to_s.inspect}].keys"
+      end
+    end
+
+    def model_expr(klass)
+      klass.name || "Model"
+    end
+
     def column_migration_hint(klass, field, types)
       type = types.is_a?(Hash) ? types[field.to_sym] : types
       column = [field, type].compact.join(":")

data/lib/permittable/contract.rb

@@ -20,8 +20,9 @@ module Permittable
   #   * A Contract always ENFORCES. Monitor mode is a request-rollout switch;
   #     standalone callers read the Result instead, so the app-wide
   #     `Permittable.mode` is ignored here.
-  #   * The router's bookkeeping keys (controller/action/format) get no
-  #     exemption from `unknown:` checking — standalone input has no router.
+  #   * The router's bookkeeping keys (controller/action/format), path
+  #     parameters and ParamsWrapper's key get no exemption from `unknown:`
+  #     checking — standalone input has no router and no request.
   #   * No memoization: every #call validates fresh, so one frozen Contract
   #     is safely reusable and shareable.
   #
@@ -76,6 +77,14 @@ module Permittable
       @host_class.permittable_contracts.last
     end
 
+    # The contract's fields, which is also what makes a Contract usable as a
+    # field group: `use SomeContract` inside a permit_params block splices
+    # them in, so a webhook payload and a controller action can share one
+    # definition instead of two that drift.
+    def fields
+      rule[:fields]
+    end
+
     # RSpec-matcher parity with controllers: `expect(MyContract).to
     # permit_param(:email)` reads the registry through these. A standalone
     # contract covers every "action", so the argument is irrelevant.

data/lib/permittable/error_envelope.rb

@@ -1,12 +1,49 @@
 module Permittable
-  # One home for the error envelope: prefer the host's #render_error when the
-  # controller defines one (e.g. concerns_on_rails' Respondable), otherwise
-  # render the identical inline shape — and the single place to change when
-  # e.g. an RFC 9457 problem+json mode lands.
+  # One home for the error response, in either of two shapes.
+  #
+  # `:envelope` (the default) is the gem's original shape: the host's
+  # #render_error when the controller defines one (e.g. concerns_on_rails'
+  # Respondable), otherwise the identical inline JSON.
+  #
+  # `:problem` renders RFC 9457 Problem Details — `application/problem+json`
+  # with type/title/status/detail/instance members and the field violations as
+  # an `errors` extension. Set it app-wide, because the error format of an API
+  # is a property of the API rather than of any one contract:
+  #
+  #   # config/initializers/permittable.rb
+  #   Permittable.error_format = :problem
+  #   Permittable.problem_base_uri = "https://api.example.com/problems"
+  #
+  # Choosing `:problem` deliberately opts OUT of #render_error delegation: a
+  # host envelope and a problem document are two answers to the same question,
+  # and the explicit setting is the one to honour.
   module ErrorEnvelope
     module_function
 
+    PROBLEM_MEDIA_TYPE = "application/problem+json".freeze
+
+    # The two statuses this gem raises, plus the Rails 7.2+ spelling of 422.
+    # Kept as a literal so a problem document can carry a numeric status
+    # without activesupport-only hosts needing Rack; anything else defers to
+    # Rack::Utils when the host has it.
+    STATUS_CODES = { bad_request: 400, unprocessable_entity: 422, unprocessable_content: 422 }.freeze
+
+    # A short human-readable summary of the problem TYPE (RFC 9457 §3.1.2), so
+    # it describes the kind of failure, not this instance of it: a missing
+    # `root:` means the request envelope itself is wrong, while a field
+    # violation means a well-formed request said something invalid.
+    PROBLEM_TYPES = {
+      400 => ["malformed-request", "Malformed request"].freeze,
+      422 => ["invalid-parameters", "Invalid parameters"].freeze
+    }.freeze
+
     def render(controller, message:, status:, code: nil, details: nil)
+      return render_problem(controller, message: message, status: status, details: details) if Permittable.error_format == :problem
+
+      render_envelope(controller, message: message, status: status, code: code, details: details)
+    end
+
+    def render_envelope(controller, message:, status:, code: nil, details: nil)
       if controller.respond_to?(:render_error)
         # errors: only when there are details — a host may document its
         # render_error contract as `(message:, status:, code:)`, and an
@@ -21,5 +58,43 @@ module Permittable
         controller.render(json: { success: false, error: error }, status: status)
       end
     end
+
+    # Members are emitted in the order RFC 9457 documents them, so the wire
+    # format is stable and readable. `instance` is omitted rather than guessed
+    # when the host cannot name the request path (a params duck, a job).
+    def render_problem(controller, message:, status:, details: nil)
+      numeric = status_code(status)
+      slug, title = PROBLEM_TYPES.fetch(numeric, ["invalid-parameters", "Invalid parameters"])
+      problem = { type: problem_type(slug), title: title }
+      problem[:status] = numeric if numeric
+      problem[:detail] = message
+      instance = request_path(controller)
+      problem[:instance] = instance if instance
+      problem[:errors] = details if details && !details.empty?
+      controller.render(json: problem, status: status, content_type: PROBLEM_MEDIA_TYPE)
+    end
+
+    # RFC 9457: an absent `type` means "about:blank", so that is the honest
+    # default until an app publishes documents to point at.
+    def problem_type(slug)
+      base = Permittable.problem_base_uri
+      return "about:blank" unless base
+
+      "#{base.to_s.chomp('/')}/#{slug}"
+    end
+
+    def status_code(status)
+      return status if status.is_a?(Integer)
+
+      symbol = status.to_sym
+      STATUS_CODES[symbol] ||
+        (defined?(Rack::Utils) && Rack::Utils::SYMBOL_TO_STATUS_CODE[symbol])
+    end
+
+    def request_path(controller)
+      return nil unless controller.respond_to?(:request) && controller.request.respond_to?(:path)
+
+      controller.request.path
+    end
   end
 end