permission_forge 0.14.1 → 0.15.0

data/lib/permission_forge/admin/settings_catalog.rb

@@ -44,7 +44,7 @@ module PermissionForge
           example: 'Rails.application.credentials.dig(:permission_forge, :password)'),
         d(:base_controller_class, 'admin_access', :class, example: "'::AdminController'"),
         d(:admin_assignment_authorization, 'admin_access', :hook,
-          example: '->(controller, target, user_ids, action) { controller.current_user&.admin? }'),
+          example: '->(controller, target, user_ids, action) { PermissionForge.current_user&.admin? }'),
 
         d(:user_class, 'people', :class, example: "'User'"),
         d(:current_user_resolver, 'people', :hook, example: '-> { ::Current.user if defined?(::Current) && ::Current.respond_to?(:user) }'),
@@ -69,18 +69,21 @@ module PermissionForge
 
         d(:auto_apply_masked_attributes, 'masked_attributes', :enum, options: %i[auto list off]),
         d(:masked_write_protection, 'masked_attributes', :enum, options: %i[skip raise off]),
-        d(:masked_attributes_nil_user_strategy, 'masked_attributes', :enum, options: %i[bypass hide]),
+        d(:masked_attributes_nil_user_strategy, 'masked_attributes', :enum,
+          options: Configuration::StrategyValues::ALLOWED[:masked_attributes_nil_user_strategy]),
         d(:hidden_attribute_value, 'masked_attributes', :str, nil_label: :nil),
         d(:omit_hidden_in_attributes_hash, 'masked_attributes', :bool),
         d(:mask_virtual_attributes, 'masked_attributes', :enum, options: %i[off auto list]),
 
         d(:nil_user_strategy, 'record_rules', :enum, options: %i[bypass deny raise]),
+        d(:no_read_access_strategy, 'record_rules', :enum, options: Configuration::StrategyValues::ALLOWED[:no_read_access_strategy]),
         d(:on_rule_bypass, 'record_rules', :hook, example: '->(user:, resource:, reason:) { Rails.logger.info(...) }'),
         d(:auto_query_scoping, 'record_rules', :enum, options: %i[off filter_only], ladder: 'enforce'),
         d(:unscoped_query_detection, 'record_rules', :enum, options: %i[off log raise], ladder: 'detect'),
         d(:unscoped_query_detection_environments, 'record_rules', :list),
         d(:database_row_level_security, 'record_rules', :bool, ladder: 'database'),
         d(:rls_session_variable, 'record_rules', :str),
+        d(:rule_secret_column_patterns, 'record_rules', :list),
 
         d(:controller_action_discovery, 'controller_actions', :bool),
         d(:controller_action_resolver, 'controller_actions', :hook,
@@ -111,7 +114,8 @@ module PermissionForge
         d(:audit_user_class, 'audit_trail', :class, example: "'User'"),
         d(:audit_events, 'audit_trail', :enum, options: %i[auto true false]),
         d(:audit_actor_resolver, 'audit_trail', :hook, nil_label: :default,
-                                                       example: '->(controller) { controller.current_user }'),
+                                                       example: '->(controller) { Session.find_by(id: ' \
+                                                                'controller.request.cookie_jar.signed[:session_id])&.user }'),
         d(:audit_request_context, 'audit_trail', :hook, nil_label: :default,
                                                         example: '->(controller) { { request_id: controller.request.request_id, ' \
                                                                  'ip: controller.request.remote_ip } }'),
@@ -121,20 +125,21 @@ module PermissionForge
         d(:audit_log_subscriber, 'audit_trail', :bool),
         d(:audit_retention_period, 'audit_trail', :num, unit: :seconds, nil_label: :nil),
         d(:audit_log_authorization, 'audit_trail', :hook, nil_label: :default,
-                                                          example: '->(controller) { controller.current_user&.auditor? }'),
+                                                          example: '->(controller) { PermissionForge.current_user&.auditor? == true }'),
 
         d(:tenant_model, 'multi_tenancy', :class, nil_label: :disabled, example: "'Account'"),
         d(:tenant_column, 'multi_tenancy', :str, nil_label: :disabled),
 
         d(:api_enabled, 'admin_api', :bool),
-        d(:api_auth, 'admin_api', :hook, example: '->(controller) { controller.current_user&.admin? }'),
+        d(:api_auth, 'admin_api', :hook, example: '->(controller) { PermissionForge.current_user&.admin? }'),
         d(:api_base_controller_class, 'admin_api', :class, example: "'::Api::BaseController'"),
         d(:api_action_authorization, 'admin_api', :hook,
-          example: '->(controller, action, record) { controller.current_user&.admin? }'),
+          example: '->(controller, action, record) { PermissionForge.current_user&.admin? }'),
         d(:api_assignment_authorization, 'admin_api', :hook,
-          example: '->(controller, permission_set, user_ids) { controller.current_user&.admin? }'),
+          example: '->(controller, permission_set, user_ids) { PermissionForge.current_user&.admin? }'),
         d(:api_require_authorization, 'admin_api', :bool),
         d(:api_stats_require_admin, 'admin_api', :bool),
+        d(:api_stats_authorization, 'admin_api', :hook, example: '->(controller) { PermissionForge.current_user&.admin? }'),
         d(:api_record_identifier, 'admin_api', :enum, options: %i[uuid id]),
         d(:api_default_per_page, 'admin_api', :num, unit: :records),
         d(:api_max_per_page, 'admin_api', :num, unit: :records),
@@ -179,23 +184,42 @@ module PermissionForge
 
           :warn
         },
-        'unconfigured_field_strategy' => ->(config) { config.unconfigured_field_strategy.to_s == 'pass_through' ? :warn : nil },
+        # :warn lets an unconfigured field through as :pass_through does (it only logs it): the audit's
+        # unconfigured_fields_pass and Home's privacy card count both.
+        'unconfigured_field_strategy' => ->(config) { %w[pass_through warn].include?(config.unconfigured_field_strategy.to_s) ? :warn : nil },
         'masked_write_protection' => ->(config) { config.masked_write_protection.to_s == 'off' ? :warn : :ok },
         'audit_trail_enabled' => ->(config) { config.audit_trail_enabled ? :ok : :warn },
         'audit_events' => ->(config) { AuditLog.recording_problem(config) ? :warn : :ok },
         'gdpr_defaults' => ->(config) { config.gdpr_defaults ? :ok : nil },
         'nil_user_strategy' => ->(config) { config.nil_user_strategy.to_s == 'bypass' ? nil : :ok },
-        'masked_attributes_nil_user_strategy' => ->(config) { config.hide_masked_attributes_without_user? ? :ok : nil },
+        'no_read_access_strategy' => ->(config) { config.deny_record_reads_without_read_access? ? :ok : nil },
+        'masked_attributes_nil_user_strategy' => ->(config) { config.hide_masked_attributes_without_user_in_requests? ? :ok : nil },
         'extra_fields_default_access' => ->(config) { config.grant_extra_fields_by_default? ? nil : :ok },
-        'unconfigured_action_strategy' => ->(config) { config.allow_unconfigured_actions? ? nil : :ok },
+        # :allow is the opt-out from the :block default: the audit's unconfigured_actions_allowed.
+        'unconfigured_action_strategy' => ->(config) { config.allow_unconfigured_actions? ? :warn : :ok },
         'action_guard_nil_user_strategy' => ->(config) { config.action_guard_nil_user_bypass? ? nil : :ok }
       }.freeze
 
+      # Risk rules that also read the data: key => ->(config, attention) { ... },
+      # `attention` being the page's AttentionItems. auto_query_scoping off is a
+      # risk only while record rules are in force that it leaves to find_by /
+      # permission_scoped: the rules the Home "Record rules" card lists
+      # (AttentionItems#unenforced_rules), so both pages warn together.
+      DATA_RISKS = {
+        'auto_query_scoping' => lambda { |config, attention|
+          next :ok if config.auto_query_scoping_enabled?
+
+          attention.unenforced_rules.any? ? :warn : nil
+        }
+      }.freeze
+
       RECOMMENDED = {
         'conditional_sets_strict_mode' => 'true',
+        'auto_query_scoping' => ':filter_only',
         'api_require_authorization' => 'true',
         'admin_tenantless_access' => ':deny',
         'unconfigured_field_strategy' => ':block',
+        'unconfigured_action_strategy' => ':block',
         'masked_write_protection' => ':skip',
         'audit_trail_enabled' => 'true',
         'audit_events' => ':auto',
@@ -206,10 +230,13 @@ module PermissionForge
         name.to_s.delete_prefix('::') == 'ActionController::Base'
       end
 
-      def initialize(configuration: PermissionForge.configuration, values: SettingsValues.new)
+      # @param attention [AttentionItems, nil] the page's attention items
+      #   (shared with the Home badge); built on first use when nil
+      def initialize(configuration: PermissionForge.configuration, values: SettingsValues.new, attention: nil)
         @configuration = configuration
         @defaults = Configuration.new
         @values = values
+        @attention = attention
       end
 
       def rows
@@ -233,6 +260,20 @@ module PermissionForge
         rows.count(&:ok?)
       end
 
+      # What Home lists as needing attention (AttentionItems#total, the
+      # page's own items): the health summary says it, so Settings never
+      # calls the setup good while Home warns (R1 #93).
+      #
+      # @return [Integer]
+      def attention_count
+        attention.total
+      end
+
+      # Nothing to fix: no risky setting and nothing on Home.
+      def healthy?
+        risky_rows.empty? && attention_count.zero?
+      end
+
       def recommended_value(key)
         row(key)&.recommended
       end
@@ -250,7 +291,18 @@ module PermissionForge
         key = definition.key
         value = @values.normalize(definition, read(@configuration, key))
         Row.new(definition: definition, value: value, default: @values.normalize(definition, read(@defaults, key)),
-                hook_state: (value if definition.type == :hook), risk: RISKS[key]&.call(@configuration))
+                hook_state: (value if definition.type == :hook), risk: risk_of(key))
+      end
+
+      def risk_of(key)
+        data_risk = DATA_RISKS[key]
+        return data_risk.call(@configuration, attention) if data_risk
+
+        RISKS[key]&.call(@configuration)
+      end
+
+      def attention
+        @attention ||= AttentionItems.new(configuration: @configuration)
       end
 
       def read(config, key)

data/lib/permission_forge/admin/state_label.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Admin
+    # The one registry of the words and glyphs of every state the admin shows:
+    # a field's configured level, an effective outcome, a CRUD cell, an action
+    # state, a lock and an actor kind. A state is a [kind, state] pair; its
+    # word is the locale key `ui.states.<kind>.<state>` and its glyph is
+    # here, so a page never pairs a glyph with a word of its own (R4 #52:
+    # "⊘ Hidden by muting" in one place, "∅ Hidden" for the same field in the
+    # next). The helpers that draw a state (pf_state_badge, pf_state_word,
+    # pf_level_badge, pf_state_cell, pf_lock_badge, ...) read it; no template
+    # looks a state key up itself (release_readiness/state_key_guard_test.rb),
+    # and two keys with the same English word in the label namespaces fail
+    # i18n_test.rb.
+    #
+    # Two kinds keep their words where they were until the 0.16 merge
+    # (NAMESPACES): the CRUD cell (shared.crud_cell) and the action states
+    # (resource_actions.states). A state worded by another kind's key says so
+    # in SHARED (one word, one key).
+    #
+    #   StateLabel.for(:field_level, 'masked').to_s  # => "•• Masked"
+    #   StateLabel.word(:actor, :unknown)            # => "Unknown"
+    #
+    # @api private
+    module StateLabel
+      # kind => { state => glyph }. A kind whose states have no glyph of their
+      # own (a lock draws an icon, an actor is a name) maps them to nil.
+      GLYPHS = {
+        field_level: { 'hidden' => '∅', 'masked' => '••', 'read' => '◉', 'edit' => '✎',
+                       'leave' => '–', 'mask' => '••', 'hide' => '⊘', 'none' => '–' },
+        effective: { 'granted' => '✓', 'blocked' => '⊘', 'none' => '–', 'hidden_by_muting' => '⊘' },
+        crud: { 'allowed' => '✓', 'no' => '–', 'muted' => '⊘', 'unchanged' => '–', 'needs_read' => '–' },
+        action: { 'permitted' => '✓', 'not_permitted' => '–', 'blocked' => '⊘', 'unchanged' => '–', 'none' => '–' },
+        lock: { 'locked' => nil },
+        actor: { 'api' => nil, 'basic_auth' => nil, 'system' => nil, 'unknown' => nil, 'user' => nil }
+      }.freeze
+
+      # Kinds whose words stay in their own namespace until 0.16 (allow-listed
+      # in i18n_test.rb's label lint).
+      NAMESPACES = { crud: 'permission_forge.shared.crud_cell', action: 'permission_forge.resource_actions.states' }.freeze
+      # Locale keys under a namespace that are not the state's own name.
+      KEY_NAMES = { [:crud, 'needs_read'] => 'needs_read_short' }.freeze
+      # A state worded by another kind's key: an action no set configures is
+      # "Not configured", the field level's word.
+      SHARED = { [:action, 'none'] => [:field_level, 'none'] }.freeze
+
+      # One state: its glyph (nil when the kind has none) and its word.
+      Label = Data.define(:kind, :state, :glyph, :word) do
+        # "glyph word", or the word alone.
+        def to_s = glyph ? "#{glyph} #{word}" : word
+      end
+
+      module_function
+
+      # @param kind [Symbol] one of GLYPHS' kinds
+      # @param state [String, Symbol]
+      # @param default [String, nil] the word for a state the registry does
+      #   not have (an actor type outside the catalogue is shown as stored);
+      #   without it such a state raises
+      # @return [Label]
+      # @raise [ArgumentError] an unknown kind, or an unknown state without `default`
+      def for(kind, state, default: nil)
+        kind = kind.to_sym
+        state = state.to_s
+        glyphs = GLYPHS.fetch(kind) { raise ArgumentError, "Unknown state kind: #{kind.inspect}" }
+        unless glyphs.key?(state)
+          raise ArgumentError, "Unknown #{kind} state: #{state.inspect}" if default.nil?
+
+          return Label.new(kind: kind, state: state, glyph: nil, word: default.to_s)
+        end
+
+        Label.new(kind: kind, state: state, glyph: glyphs[state], word: I18n.t(key(kind, state)))
+      end
+
+      # @return [String] the state's word, in the current locale
+      def word(kind, state, default: nil) = self.for(kind, state, default: default).word
+
+      # @return [String, nil] the state's glyph
+      def glyph(kind, state) = GLYPHS.fetch(kind.to_sym).fetch(state.to_s)
+
+      # @return [String] the locale key of the state's word
+      def key(kind, state)
+        kind = kind.to_sym
+        state = state.to_s
+        shared = SHARED[[kind, state]]
+        return key(*shared) if shared
+
+        namespace = NAMESPACES.fetch(kind) { "permission_forge.ui.states.#{kind}" }
+        "#{namespace}.#{KEY_NAMES.fetch([kind, state], state)}"
+      end
+
+      # @return [Array<Array(Symbol, String)>] every [kind, state] of the registry
+      def states = GLYPHS.flat_map { |kind, glyphs| glyphs.keys.map { |state| [kind, state] } }
+    end
+  end
+end

data/lib/permission_forge/admin_method_override.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'rack/method_override'
+
+module PermissionForge
+  # Rack::MethodOverride for the admin screens, in the engine's own
+  # middleware stack (PermissionForge::Engine: it runs only for requests the
+  # host's router hands to the mounted engine). The admin's edit and delete
+  # forms POST with a hidden `_method` (patch, delete), which this turns into
+  # the verb the route wants. A full-stack host already has
+  # Rack::MethodOverride, and a second pass is a no-op (it only rewrites a
+  # POST); an API-only host (`rails new --api`) has none, and every such form
+  # answered 404 — the engine brings its own, so the host adds nothing for it
+  # (docs/admin-ui.md#api-only-applications names the three session
+  # middlewares only).
+  #
+  # The JSON API's paths (`<mount>/api…`) are left alone by this override:
+  # a JSON client says the verb it means. In a full-stack host the
+  # application's own Rack::MethodOverride runs before the router for every
+  # path, the API's included, as Rails has it (a `_method` field or an
+  # `X-HTTP-Method-Override` header on a POST then changes its verb there);
+  # api_auth and the API's guards apply either way.
+  #
+  # It keeps the app it wraps under its own name: Rack::MethodOverride's
+  # instance variable is not part of Rack's API.
+  #
+  # @api private
+  class AdminMethodOverride < Rack::MethodOverride
+    # The engine's JSON API, below the mount point (PATH_INFO inside the engine).
+    API_PATH = %r{\A/api(?:/|\.|\z)}
+
+    # @param app [#call] the engine's next middleware
+    def initialize(app)
+      super
+      @pf_app = app
+    end
+
+    def call(env)
+      return @pf_app.call(env) if API_PATH.match?(env[Rack::PATH_INFO].to_s)
+
+      super
+    end
+  end
+end

data/lib/permission_forge/api/schema.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+require 'time'
+
+module PermissionForge
+  module Api
+    # The one declaration of what the Admin JSON API answers: every envelope
+    # (a record, a page of records, the rows one request created, an error),
+    # the messages each error status carries, which answers have no body,
+    # every serializer's payload (its keys and their types), the two results
+    # a controller builds itself (stats, a bulk assignment), and what each
+    # endpoint answers when it succeeds.
+    #
+    #   { "data": { ... } }                                        single
+    #   { "data": { ... }, "meta": { "cache": { ... } } }          single_with_cache (one assignment)
+    #   { "data": [ ... ], "meta": { "pagination": { ... } } }     collection
+    #   { "data": [ ... ] }                                        list (generate_fields)
+    #   { "error": { "status": 404, "messages": "..." } }          error
+    #
+    # A type is a Symbol from TYPES; a trailing `?` allows null
+    # (`:string?`). A Hash is an object with exactly those keys, a one-element
+    # Array a list of that element. `:foreign_identifier` marks the numeric id
+    # of another PermissionForge record, which the API's URLs do not take
+    # under `api_record_identifier = :uuid`: its value is unchanged (the
+    # record's id), and the key after it, `:foreign_uuid`, names the same
+    # record by its uuid (`permission_set_id`, `permission_set_uuid`:
+    # Serializers::BaseSerializer.reference) — answer-only: no endpoint
+    # takes it, the `_id` key changes a reference.
+    #
+    # test/permission_forge/api/envelope_schema_test.rb asserts every route,
+    # in every error class, against this module and every serializer's keys
+    # against PAYLOADS; `rake docs:api` renders the json samples of
+    # docs/admin-api.md from it (Docs::ApiSamples).
+    #
+    # @api private
+    module Schema
+      UUID = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/
+      # What a value of each type is, as the JSON answer carries it.
+      TYPES = {
+        integer: ->(value) { value.is_a?(Integer) },
+        string: ->(value) { value.is_a?(String) },
+        boolean: ->(value) { [true, false].include?(value) },
+        uuid: ->(value) { value.is_a?(String) && value.match?(UUID) },
+        time: ->(value) { value.is_a?(String) && Check.iso8601?(value) },
+        foreign_identifier: ->(value) { value.is_a?(Integer) },
+        foreign_uuid: ->(value) { value.is_a?(String) && value.match?(UUID) },
+        host_key: ->(value) { value.is_a?(Integer) || value.is_a?(String) },
+        host_key_list: ->(value) { value.is_a?(Array) && value.all? { |item| item.is_a?(Integer) || item.is_a?(String) } },
+        string_list: ->(value) { value.is_a?(Array) && value.all?(String) },
+        object: ->(value) { value.is_a?(Hash) },
+        # `messages` of a 422: a field (a parameter, an attribute, `base`)
+        # mapped to its messages.
+        field_messages: lambda { |value|
+          value.is_a?(Hash) && !value.empty? &&
+            value.all? { |field, list| field.is_a?(String) && list.is_a?(Array) && !list.empty? && list.all?(String) }
+        }
+      }.freeze
+
+      # One serializer's payload per entry, named after the serializer
+      # (`permission_set` = Serializers::PermissionSetSerializer), keys in
+      # the serializer's order.
+      PAYLOADS = {
+        permission_set: {
+          id: :integer, uuid: :uuid, name: :string, description: :string?,
+          is_active: :boolean, is_editable: :boolean, is_muting: :boolean,
+          requires_session_flag: :string?, allowed_ips: :string?, allowed_ip_list: :string_list,
+          allowed_hours_start: :integer?, allowed_hours_end: :integer?,
+          permission_set_group_id: :foreign_identifier?, permission_set_group_uuid: :foreign_uuid?, created_at: :time, updated_at: :time
+        },
+        resource: {
+          id: :integer, uuid: :uuid, permission_set_id: :foreign_identifier, permission_set_uuid: :foreign_uuid,
+          name: :string, description: :string?, is_active: :boolean, is_editable: :boolean,
+          read_access: :boolean, create_access: :boolean, edit_access: :boolean, delete_access: :boolean,
+          view_all: :boolean, modify_all: :boolean,
+          created_at: :time, updated_at: :time
+        },
+        resource_field: {
+          id: :integer, uuid: :uuid, resource_id: :foreign_identifier, resource_uuid: :foreign_uuid,
+          name: :string, label: :string, description: :string?, is_active: :boolean, is_editable: :boolean,
+          read_access: :boolean, edit_access: :boolean, mask_access: :boolean, mask_strategy: :string,
+          created_at: :time, updated_at: :time
+        },
+        resource_action: {
+          id: :integer, uuid: :uuid, resource_id: :foreign_identifier, resource_uuid: :foreign_uuid,
+          name: :string, label: :string?, description: :string?, is_permitted: :boolean, is_active: :boolean,
+          created_at: :time, updated_at: :time
+        },
+        permission_set_rule: {
+          id: :integer, uuid: :uuid, permission_set_id: :foreign_identifier, permission_set_uuid: :foreign_uuid,
+          resource_id: :foreign_identifier, resource_uuid: :foreign_uuid,
+          name: :string, failure_message: :string?, join_type: :string?,
+          field_name: :string, field_value: :string, field_accessor_path: :string?,
+          operator: :string, include_nulls: :boolean, is_active: :boolean, is_editable: :boolean,
+          created_at: :time, updated_at: :time
+        },
+        permission_set_user: {
+          id: :integer, uuid: :uuid, permission_set_id: :foreign_identifier, permission_set_uuid: :foreign_uuid,
+          user_id: :host_key, expires_at: :time?, created_at: :time, updated_at: :time
+        },
+        audit_event: {
+          id: :integer, uuid: :uuid, occurred_at: :time, event: :string, category: :string,
+          actor_type: :string, actor_id: :string?, actor_label: :string?, source: :string,
+          record_type: :string?, record_id: :string?, record_uuid: :string?, record_label: :string?,
+          permission_set_id: :foreign_identifier?, permission_set_uuid: :string?, subject_user_id: :string?,
+          data: :object, reason: :string?, request_id: :string?, ip: :string?, correlation_id: :string?, created_at: :time
+        },
+        permission_set_group: {
+          id: :integer, uuid: :uuid, name: :string, description: :string?, is_active: :boolean, is_editable: :boolean,
+          created_at: :time, updated_at: :time
+        },
+        permission_set_group_user: {
+          id: :integer, uuid: :uuid, permission_set_group_id: :foreign_identifier, permission_set_group_uuid: :foreign_uuid,
+          user_id: :host_key, created_at: :time, updated_at: :time
+        }
+      }.freeze
+
+      # Cache::Outcome as the API answers it: what one change did to the
+      # cached permissions (a bulk assignment, one assignment).
+      CACHE = { confirmed: :boolean?, process_local: :boolean, unconfirmed: :integer?, in_request: :boolean }.freeze
+
+      # The payloads a controller builds itself (no serializer).
+      RESULTS = {
+        stats: {
+          permission_sets_count: :integer, active_sets_count: :integer, resources_count: :integer,
+          rules_count: :integer, groups_count: :integer, users_count: :integer
+        },
+        # Services::BulkPermissionSetAssignment's counts, its Cache::Outcome
+        # and the ids that named nobody. `invalidated` is null inside a
+        # caller's transaction.
+        bulk_assignment: {
+          assigned: :integer, revoked: :integer, invalidated: :integer?,
+          cache: CACHE,
+          skipped: :host_key_list
+        }
+      }.freeze
+
+      PAGINATION = { page: :integer, per_page: :integer, total_count: :integer }.freeze
+
+      # The success envelopes, each around a payload spec.
+      ENVELOPES = {
+        single: ->(payload) { { data: payload } },
+        # One assignment made or revoked, and its Cache::Outcome.
+        single_with_cache: ->(payload) { { data: payload, meta: { cache: CACHE } } },
+        collection: ->(payload) { { data: [payload], meta: { pagination: PAGINATION } } },
+        list: ->(payload) { { data: [payload] } }
+      }.freeze
+
+      # What `messages` is under each error status. A 422 maps fields to
+      # their messages; the others carry one sentence.
+      ERRORS = { 400 => :string, 401 => :string, 403 => :string, 404 => :string, 422 => :field_messages }.freeze
+
+      # The answers without a body, and when: a delete (204), the 401 while
+      # config.api_auth is not set, the 404 while config.api_enabled is off
+      # (it does not reveal that an API exists under the mount).
+      BODILESS = { 204 => :deleted, 401 => :api_auth_not_set, 404 => :api_disabled }.freeze
+
+      # What an endpoint answers when it succeeds: its status, envelope and
+      # payload (PAYLOADS or RESULTS); the catch-all is always its 404.
+      Endpoint = Data.define(:status, :envelope, :payload)
+
+      crud = lambda do |name|
+        { 'index' => Endpoint.new(200, :collection, name), 'show' => Endpoint.new(200, :single, name),
+          'create' => Endpoint.new(201, :single, name), 'update' => Endpoint.new(200, :single, name),
+          'destroy' => Endpoint.new(204, nil, nil) }
+      end
+      prefixed = ->(controller, actions) { actions.transform_keys { |action| "#{controller}##{action}" } }
+
+      # Keyed by "controller#action", the controller under permission_forge/api/.
+      ENDPOINTS = {
+        'dashboard#show' => Endpoint.new(200, :single, :stats),
+        'audit_events#index' => Endpoint.new(200, :collection, :audit_event),
+        'audit_events#show' => Endpoint.new(200, :single, :audit_event),
+        **prefixed.call('permission_sets', crud.call(:permission_set).merge('clone' => Endpoint.new(201, :single, :permission_set))),
+        **prefixed.call('resources', crud.call(:resource).merge('generate_fields' => Endpoint.new(201, :list, :resource_field))),
+        **prefixed.call('resource_fields', crud.call(:resource_field)),
+        **prefixed.call('resource_actions', crud.call(:resource_action)),
+        **prefixed.call('permission_set_rules', crud.call(:permission_set_rule)),
+        **prefixed.call('permission_set_users', crud.call(:permission_set_user).slice('index')
+                                                  .merge('create' => Endpoint.new(201, :single_with_cache, :permission_set_user),
+                                                         'destroy' => Endpoint.new(200, :single_with_cache, :permission_set_user),
+                                                         'bulk' => Endpoint.new(200, :single, :bulk_assignment))),
+        **prefixed.call('permission_set_groups', crud.call(:permission_set_group)
+                                                   .merge('clone' => Endpoint.new(201, :single, :permission_set_group))),
+        **prefixed.call('permission_set_group_users', crud.call(:permission_set_group_user).slice('index', 'create', 'destroy')),
+        'unmatched_routes#show' => Endpoint.new(404, :error, nil)
+      }.freeze
+
+      module_function
+
+      # @param name [Symbol] a PAYLOADS or RESULTS entry
+      # @return [Hash{Symbol => Symbol, Hash}] the keys and their types
+      def payload(name)
+        PAYLOADS.fetch(name) { RESULTS.fetch(name) }
+      end
+
+      # @return [Array<Symbol>] the keys of a payload, in order
+      def payload_keys(name) = payload(name).keys
+
+      # @return [Array<Symbol>] the keys of a payload that hold another record's numeric id
+      #   (each followed by its `:foreign_uuid` key)
+      def foreign_identifiers(name)
+        payload(name).select { |_key, type| type.is_a?(Symbol) && base_type(type) == :foreign_identifier }.keys
+      end
+
+      # The spec of a success envelope around a payload.
+      def envelope(kind, payload_name)
+        ENVELOPES.fetch(kind).call(payload(payload_name))
+      end
+
+      # The spec of an error answer under `status`.
+      def error_envelope(status)
+        { error: { status: [:exactly, status], messages: ERRORS.fetch(status) } }
+      end
+
+      # An error answer: the body the API renders for `status`.
+      #
+      # @return [Hash]
+      def error_body(status, messages)
+        { 'error' => { 'status' => status, 'messages' => messages } }
+      end
+
+      # What is wrong with a parsed JSON answer of an endpoint's success.
+      #
+      # @param endpoint [Endpoint]
+      # @param body [Hash, nil] the parsed body (nil when there is none)
+      # @return [Array<String>] empty when it matches
+      def success_problems(endpoint, body)
+        return error_problems(endpoint.status, body) if endpoint.envelope == :error
+        return body.nil? ? [] : ["#{endpoint.status}: a body where none is declared"] if endpoint.envelope.nil?
+
+        problems(body, envelope(endpoint.envelope, endpoint.payload))
+      end
+
+      # What is wrong with a parsed JSON error answer under `status`; nil
+      # (no body) only where BODILESS declares it.
+      #
+      # @return [Array<String>]
+      def error_problems(status, body)
+        return BODILESS.key?(status) ? [] : ["#{status}: no body, and BODILESS does not declare one"] if body.nil?
+        return ["#{status}: not an error status of the schema (#{ERRORS.keys.join(', ')})"] unless ERRORS.key?(status)
+
+        problems(body, error_envelope(status))
+      end
+
+      # What is wrong with `value` against `spec`, one message per problem,
+      # each with its JSON path (Check).
+      #
+      # @return [Array<String>]
+      def problems(value, spec, path = '$') = Check.problems(value, spec, path)
+
+      def base_type(type) = type.to_s.delete_suffix('?').to_sym
+
+      # Walks a parsed answer along a spec (a Hash, a one-element Array, a
+      # type Symbol, or [:exactly, value]).
+      #
+      # @api private
+      module Check
+        # A value of the answer and its JSON path.
+        Node = Data.define(:value, :path) do
+          def refused(expected) = ["#{path}: expected #{expected}, got #{value.inspect[0, 60]}"]
+          def at(key) = "#{path}.#{key}"
+        end
+
+        module_function
+
+        def problems(value, spec, path)
+          node = Node.new(value, path)
+          case spec
+          when Hash then object_problems(node, spec)
+          when Array then spec.first == :exactly ? exact_problems(node, spec.last) : list_problems(node, spec.first)
+          else type_problems(node, spec)
+          end
+        end
+
+        def object_problems(node, spec)
+          value = node.value
+          return node.refused('an object') unless value.is_a?(Hash)
+
+          keys = value.keys.map(&:to_s)
+          key_problems(node, keys, spec.keys.map(&:to_s)) + value_problems(node, spec)
+        end
+
+        # The values of the declared keys the answer has, each against its spec.
+        def value_problems(node, spec)
+          value = node.value
+          spec.flat_map { |key, inner| value.key?(key.to_s) ? problems(value[key.to_s], inner, node.at(key)) : [] }
+        end
+
+        # Keys the answer has and the spec does not, and the reverse.
+        def key_problems(node, keys, expected)
+          (keys - expected).map { |key| "#{node.at(key)}: not declared in Api::Schema" } +
+            (expected - keys).map { |key| "#{node.at(key)}: missing" }
+        end
+
+        def list_problems(node, spec)
+          value = node.value
+          return node.refused('a list') unless value.is_a?(Array)
+
+          value.each_with_index.flat_map { |item, index| problems(item, spec, "#{node.path}[#{index}]") }
+        end
+
+        def exact_problems(node, expected)
+          node.value == expected ? [] : node.refused(expected.inspect)
+        end
+
+        def type_problems(node, type)
+          value = node.value
+          return [] if value.nil? && type.to_s.end_with?('?')
+
+          TYPES.fetch(Schema.base_type(type)).call(value) ? [] : node.refused(type)
+        end
+
+        def iso8601?(text)
+          Time.iso8601(text)
+          true
+        rescue ArgumentError
+          false
+        end
+      end
+    end
+  end
+end