permission_forge 0.14.1 → 0.15.0

data/README.md

@@ -1,13 +1,14 @@
 <p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/fetijashari/permission_forge/main/docs/assets/logo-horizontal-dark.svg">
-    <img alt="PermissionForge" src="https://raw.githubusercontent.com/fetijashari/permission_forge/main/docs/assets/logo-horizontal-light.svg" width="420">
-  </picture>
+  <img alt="PermissionForge" src="https://raw.githubusercontent.com/fetijashari/permission_forge/main/docs/assets/logo-horizontal-light.svg#gh-light-mode-only" width="420">
+  <img alt="PermissionForge" src="https://raw.githubusercontent.com/fetijashari/permission_forge/main/docs/assets/logo-horizontal-dark.svg#gh-dark-mode-only" width="420">
 </p>
 
 <p align="center">
   <a href="https://github.com/fetijashari/permission_forge/actions/workflows/ci.yml"><img src="https://github.com/fetijashari/permission_forge/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://rubygems.org/gems/permission_forge"><img src="https://img.shields.io/gem/v/permission_forge" alt="Gem Version"></a>
+  <a href="https://scorecard.dev/viewer/?uri=github.com/fetijashari/permission_forge"><img src="https://api.scorecard.dev/projects/github.com/fetijashari/permission_forge/badge" alt="OpenSSF Scorecard"></a>
+  <a href="https://www.bestpractices.dev/projects/15499"><img src="https://www.bestpractices.dev/projects/15499/badge" alt="OpenSSF Best Practices"></a>
+  <a href="https://rubydoc.info/gems/permission_forge"><img src="https://img.shields.io/badge/docs-rubydoc.info-blue.svg" alt="API documentation"></a>
   <a href="https://www.ruby-lang.org"><img src="https://img.shields.io/badge/ruby-%3E%3D%203.2-ruby.svg" alt="Ruby"></a>
   <a href="https://rubyonrails.org"><img src="https://img.shields.io/badge/rails-7.1%20to%208.1-red.svg" alt="Rails"></a>
   <a href="https://github.com/fetijashari/permission_forge/blob/main/LICENSE.txt"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
@@ -69,13 +70,13 @@ sit next to one (for example Pundit for controller decisions, PermissionForge fo
 
 Add to your `Gemfile`:
 
-```ruby
+```ruby fragment
 gem 'permission_forge'
 ```
 
 Then run:
 
-```bash
+```bash run
 bundle install
 bin/rails generate permission_forge:install
 bin/rails db:migrate
@@ -84,6 +85,23 @@ bin/rails db:migrate
 This creates `config/initializers/permission_forge.rb` and a migration with 9 tables: the 8 permission tables and the
 audit log, prefixed with `permission_forge_` by default.
 
+Then mount the admin UI and give it credentials. It is behind HTTP Basic auth and answers 401 until both are set:
+
+```ruby fragment
+# config/routes.rb
+mount PermissionForge::Engine, at: "/permissions"
+```
+
+```ruby fragment
+# config/initializers/permission_forge.rb: uncomment Option A ("Admin screens")
+config.http_basic_auth_user     = ENV['PF_ADMIN_USER']
+config.http_basic_auth_password = ENV['PF_ADMIN_PASSWORD']
+```
+
+Set `PF_ADMIN_USER` and `PF_ADMIN_PASSWORD` in the environment and open `/permissions`. To sign admins in with your
+own authentication instead, see [Admin UI](https://github.com/fetijashari/permission_forge/blob/main/docs/admin-ui.md#disabling-http-basic-auth)
+(`base_controller_class`). `bin/rails permission_forge:audit` lists what is still open before production.
+
 Generator options:
 - `--skip-migration`: no migration (for apps with existing tables)
 - `--table-prefix=PREFIX`: table name prefix (default `permission_forge_`; `''` for none)
@@ -106,7 +124,7 @@ Upgrading? Read the [CHANGELOG](https://github.com/fetijashari/permission_forge/
 The generated initializer reads `Current.user` when your app has a `Current` class that answers `user` (as Rails 8's
 authentication generator creates). Otherwise point it at your own lookup:
 
-```ruby
+```ruby fragment
 # config/initializers/permission_forge.rb
 PermissionForge.configure do |config|
   config.user_class = 'User'
@@ -130,7 +148,7 @@ module, add a callback), use `Rails.application.config.to_prepare` or
 
 ### 2. Include the concern in your User model
 
-```ruby
+```ruby fragment
 class User < ApplicationRecord
   include PermissionForge::Concerns::PermissionedUser
 end
@@ -144,7 +162,7 @@ those, not the private helpers.
 
 ### 3. Protect models with row-level rules (optional)
 
-```ruby
+```ruby fragment
 class Customer < ApplicationRecord
   include PermissionForge::Concerns::PermissionScopedFindable
 end
@@ -158,7 +176,11 @@ rules for a model gets every row.
 
 ### 4. Create a Permission Set and assign it
 
-```ruby
+Run these lines in order, in one console. If a `create!` raises (a Permission Set name is unique: one made in the
+admin already holds "Sales Team"), fix it and run it again before going on: the lines after it use its record and,
+without it, fail with a database `NOT NULL` error that hides the first one.
+
+```ruby run
 pset = PermissionForge::PermissionSet.create!(name: 'Sales Team', is_active: true)
 
 resource = PermissionForge::Resource.create!(
@@ -173,16 +195,31 @@ PermissionForge::ResourceField.create!(
   read_access: true, edit_access: true
 )
 
+user = User.find_by!(email_address: 'bob@example.com') # the person who gets the set (`email:` on a Devise app)
 PermissionForge::PermissionSetUser.create!(permission_set: pset, user: user)
 ```
 
+Only `name` has a field row here. A column with no row is refused by the default
+`unconfigured_field_strategy = :block`: its getter returns `nil` and `as_json` keeps the key as `null` (a Hidden row,
+read off, leaves the key out). `PermissionForge::Services::ResourceFieldGenerator.call(resource: resource)` gives every
+column (and declared virtual field) without a row one: Hidden, `created_at` / `updated_at` included — also the columns
+that look like personal data, which get their recommended mask strategy on the row. With `grant_all: true` every row is
+readable and editable (Read-only on a Resource without Edit), unmasked, and the timestamps read-only. The admin's "Sync fields with model" adds the rows at a level you pick (under
+the default `gdpr_defaults`, "… as Read-only" starts the personal-data columns Masked). Then open the ones the set should read.
+
 Each change invalidates the cached permissions of the users it affects; the next read rebuilds them. The admin UI
-(mounted as described in [Admin UI](https://github.com/fetijashari/permission_forge/blob/main/docs/admin-ui.md)) does
-the same through forms.
+(mounted at `/permissions` in [Installation](#installation)) does the same through forms.
+
+Every change is also an audit event. Made in a console, a seed or a script, it is recorded with actor `unknown`;
+wrap it to say who and why: `PermissionForge.with_audit_actor(user: admin, reason: 'onboarding') { ... }` (see
+[Audit Log](https://github.com/fetijashari/permission_forge/blob/main/docs/audit-log.md)).
 
 ### 5. Check permissions at runtime
 
-```ruby
+Look up the same person step 4 assigned (`User.first` may be someone else, who holds no set: `false` and `{}`):
+
+```ruby run
+user = User.find_by!(email_address: 'bob@example.com') # the person you assigned in step 4
 user.can_read?('Customer')   # => true
 user.can_delete?('Customer') # => false
 user.permissions_for(:Customer)
@@ -200,10 +237,11 @@ where you call `can_*?`, or with `ControllerActionGuard`. Field access is decide
 Several defaults fail open so that installing the gem changes nothing until you configure it. Before production, go
 through this list. `bin/rails permission_forge:audit` reports most of these settings.
 
-`config.preset = :strict` closes every row below that a setting can close, except masking with nobody signed in (an
-explicit choice: see its row); a setting you make yourself always wins over the preset. New installs get the safe
-part (`action_guard_nil_user_strategy = :deny`, `conditional_sets_strict_mode = true`, `cache_backend = :rails_cache`)
-and the preset as a commented line with what it costs. The rows that need your code (`base_controller_class`,
+`config.preset = :strict` closes every row below that a setting can close (masking with nobody signed in as
+`:hide_in_requests`: hidden in web requests, stored values in jobs and the console); a setting you make yourself always
+wins over the preset. New installs get the safe part (`action_guard_nil_user_strategy = :deny`,
+`conditional_sets_strict_mode = true`, `cache_backend = :rails_cache`, `masked_attributes_nil_user_strategy =
+:hide_in_requests`) and the preset as a commented line with what it costs. The rows that need your code (`base_controller_class`,
 `admin_assignment_authorization`, `audit_log_authorization`, `user_active_check`) are not in a preset.
 `bin/rails permission_forge:audit` prints the preset and, under `:strict`, every option set looser. See
 [Presets](https://github.com/fetijashari/permission_forge/blob/main/docs/configuration.md#presets).
@@ -211,10 +249,10 @@ and the preset as a commented line with what it costs. The rows that need your c
 | Default | What it means | To close it |
 |---|---|---|
 | `nil_user_strategy = :bypass` | With no current user (jobs, console, a resolver that returns nil), `find_by`, `permission_scoped`, auto-scoping and the RLS policy apply no rules; so does the controller guard unless `action_guard_nil_user_strategy` is set | `:deny` (not found) or `:raise`. Do not include `PermissionScopedFindable` in the user model: under `:deny` sign-in lookups return nil (`permission_forge:audit` reports `user_model_scoped`) |
-| `masked_attributes_nil_user_strategy = :bypass` | Attribute readers, `attributes` and `as_json` of a masked model return the stored values when nobody is signed in, whatever `nil_user_strategy` says | `:hide` (every guarded attribute reads as hidden with no user; the primary key and the raw paths are untouched), and set the current user in the jobs and mailers that read masked models. Not part of `config.preset = :strict`. The user model (`user_class` and its subclasses) stays readable for sign-in; validations read stored values |
+| `masked_attributes_nil_user_strategy = :bypass` | Attribute readers, `attributes` and `as_json` of a masked model return the stored values when nobody is signed in, whatever `nil_user_strategy` says: in jobs and the console, and in a web request nobody is signed in to (a public page, a webhook, a controller that forgot authentication). Such a read in a web request is logged (once per model and process) and published as `field.unmasked_without_user` | `:hide_in_requests` (every guarded attribute reads as hidden in a web request with nobody signed in; jobs, rake and the console keep the stored values; new installs get it from the generator), or `:hide` (hidden everywhere: set the current user in the jobs and mailers that read masked models). The primary key and the raw paths are untouched; the user model (`user_class` and its subclasses) stays readable for sign-in; validations read stored values |
 | `response_filter_nil_user_strategy = :bypass` | `FiltersResponseAttributes` returns every attribute when there is no user | `:block` |
 | `auto_query_scoping = :off` | Only class-level `find_by` / `find_by!` and `permission_scoped` apply row rules | `:filter_only`, and use `permission_scoped` for join rules; consider RLS on PostgreSQL |
-| `unconfigured_action_strategy = :allow` | A controller action no Permission Set manages is allowed; unmapped actions are always allowed | `:block` |
+| `no_read_access_strategy = :rules_only` | A signed-in user whose Permission Sets do not grant Read on a model (no `Resource` for it at all included) has no rules there: `find_by`, `permission_scoped` and auto-scoping return every row. Only `can_read?` (or the controller guard) refuses them | `:deny` (no rows; `find_by` raises `NotAuthorizedError` for an existing record) |
 | `action_guard_nil_user_strategy = nil` | The guard follows `nil_user_strategy` (`:bypass`) for signed-out requests to mapped actions | `:deny` (new installs get it from the generator) |
 | `conditional_sets_strict_mode = false` | With an empty request context (no resolver configured), every conditional Permission Set applies, MFA- or IP-gated grants included | A `request_context_resolver` that returns the request's IP and session flags, and `true`: without a request context, conditional granting sets are then dropped and conditional muting sets still apply |
 | `mask_virtual_attributes = false` | Virtual readers (methods, store accessors, attribute-API attributes) are not masked on the model; only `PermitsAttributes` and `FiltersResponseAttributes` apply their field rows | `:auto` (or a list of models), after checking that the models' own callbacks do not need the raw values |
@@ -226,12 +264,22 @@ and the preset as a commented line with what it costs. The rows that need your c
 | `base_controller_class` / `api_base_controller_class` | With tenancy on, a request with no current tenant is refused (403) | Controllers that authenticate and set the tenant |
 | `user_active_check` | Only reported by the security audit; an inactive user keeps every grant | Revoke the assignments of users you deactivate |
 
-Upgrading from 0.13: once the last 0.13 process is gone, run `bin/rails permission_forge:cache:clear` (see the
-[CHANGELOG](https://github.com/fetijashari/permission_forge/blob/main/CHANGELOG.md)).
+Upgrading to 0.15: a controller action that maps to a Resource (in a controller that includes
+`ControllerActionGuard`) and that no Permission Set manages is now refused with 403; before 0.15 it ran.
+`bin/rails permission_forge:audit` lists those actions (`unmanaged_actions_refused`; with tenancy, each with the
+tenants that do not manage it) and the controller actions it could not check (`actions_not_checked`). Manage each one
+in a Permission Set, or opt out with `config.unconfigured_action_strategy = :allow`, which lets every signed-in user
+run them (the audit reports the opt-out as `unconfigured_actions_allowed`, medium). Actions that map to no Resource are
+never checked.
+Run `bin/rails permission_forge:audit` before you deploy (see the
+[Migration Guide](https://github.com/fetijashari/permission_forge/blob/main/docs/migration-guide.md#upgrading-to-015)).
+From 0.13: follow [From 0.13](https://github.com/fetijashari/permission_forge/blob/main/docs/migration-guide.md#from-013) — a revocation made on 0.15 does not reach what 0.13 processes have cached.
 
 Already closed by default, keep them so: `api_require_authorization = true` (API changes need
 `api_action_authorization` and `api_assignment_authorization`), `admin_tenantless_access = :deny`,
-`nested_attributes_parent_fallback = false`, `unconfigured_field_strategy = :block`, and the API is off
+`nested_attributes_parent_fallback = false`, `unconfigured_field_strategy = :block`,
+`unconfigured_action_strategy = :block` (since 0.15: a mapped controller action no Permission Set manages is refused
+with 403; `:allow`, the explicit opt-out, lets every signed-in user run it), and the API is off
 (`api_enabled = false`). If you use PostgreSQL RLS, run `bin/rails permission_forge:rls:sync` after each upgrade.
 
 See [Configuration](https://github.com/fetijashari/permission_forge/blob/main/docs/configuration.md) for every option.
@@ -265,11 +313,14 @@ Every create, update and destroy, made through the models, of a Permission Set,
 assignment or membership is written to the `audit_events` table inside the change's own transaction. Under the default
 `audit_change_failure_strategy = :raise`, a change whose event cannot be written rolls back. Each event stores the
 actor, source, request id, IP, an optional reason, a correlation id, and the changes or a snapshot of the deleted row.
-Name the person who acts, otherwise HTTP Basic admins share one name:
+Behind your own admin controller (`base_controller_class`) the actor is the user `current_user_resolver` returns.
+Under HTTP Basic auth your app's sign-in does not run in the admin, so admins share one login name unless
+`audit_actor_resolver` names them:
 
-```ruby
+```ruby fragment
 PermissionForge.configure do |config|
-  config.audit_actor_resolver = ->(controller) { controller.current_admin }
+  # Rails 8's authentication generator (with Devise: controller.request.env['warden']&.user(:user))
+  config.audit_actor_resolver = ->(controller) { Session.find_by(id: controller.request.cookie_jar.signed[:session_id])&.user }
   config.audit_retention_period = 2.years # purge: bin/rails permission_forge:audit_events:purge
 end
 ```

data/app/controllers/concerns/permission_forge/api/crud_actions.rb

@@ -16,7 +16,7 @@ module PermissionForge
     #     def collection_scope = @resource.resource_fields
     #     def current_record = @field
     #     def serializer_type = :resource_field
-    #     def record_params = pf_require_hash(:resource_field).permit(:name, :label)
+    #     def record_params = pf_record_attributes(:resource_field, PermissionForge::ResourceField, :name, :label)
     #   end
     module CrudActions
       extend ActiveSupport::Concern
@@ -71,7 +71,8 @@ module PermissionForge
       # @return [Symbol] key for serializer_for()
       def serializer_type = raise(NotImplementedError, "#{self.class}#serializer_type")
 
-      # @return [ActionController::Parameters] permitted params
+      # @return [ActiveSupport::HashWithIndifferentAccess] the attributes, in
+      #   their shapes (BaseController#pf_record_attributes)
       def record_params = raise(NotImplementedError, "#{self.class}#record_params")
 
       # @return [ActiveRecord::Base] new record built from collection_scope and params

data/app/controllers/concerns/permission_forge/api/input_shapes.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Api
+    # The one shape table of the JSON API's attribute sections
+    # (`{ "permission_set": { ... } }`): what each attribute is taken in,
+    # read through BaseController#pf_record_attributes by every endpoint
+    # that creates or updates a record. A value of another shape is a 422
+    # keyed by the attribute, every wrong attribute of the request named
+    # (`{ "is_active": ["must be true or false"] }`): never dropped, never
+    # cast into something else, never a 500. Through 0.15.0-rc strong
+    # parameters dropped a list or an object sent for a scalar with a log
+    # line, and ActiveModel cast what remained: "nope" was true, a JSON
+    # `true` for a name stored "t" (field test round 7, d-api #54 / #59).
+    #
+    # An attribute's shape is its column type's (BY_TYPE: what the model
+    # casts it to, `type_for_attribute`), unless DECLARED names one:
+    #
+    # - boolean: ParamShapes.boolean (true, false, 1, 0, and the words
+    #   true/false/t/f/on/off/1/0 in any case), stored as true or false;
+    # - text: a String;
+    # - integer: an Integer or a String of digits;
+    # - the activation conditions: `allowed_ips` a String or a list of
+    #   Strings (stored with commas; a list with no entry is refused),
+    #   an hour an integer or digits, a session flag a String — `""` clears
+    #   each;
+    # - a rule's `field_value`: a String, or a JSON number or boolean (stored
+    #   as its text: `5` → "5", `true` → "true"); a list of them, none with a
+    #   comma, only for an operator that takes several values (`in`,
+    #   `not_in`, `between`: Operators::ValueTyping::SEVERAL), stored joined
+    #   with commas;
+    # - a reference (`permission_set_group_id`): taken as sent, then read by
+    #   BaseController#with_reference_id (the id or uuid of a record; null or
+    #   "" clears it; anything else a 422 keyed by it).
+    #
+    # `null` is passed to the model for every attribute: a nullable column
+    # is cleared, a NOT NULL one answers its own validation (422 keyed by
+    # the attribute). An attribute whose type has no shape here (none of the
+    # gem's: the input_shapes test checks) is passed on as sent.
+    #
+    # @api private
+    module InputShapes
+      # How one shape reads a value: the value to store, or a Refusal.
+      Refusal = Data.define(:message)
+
+      # The 422 of a section with values of the wrong shape: every attribute
+      # and its message.
+      #
+      # @api private
+      class Refused < ParamShapes::InvalidParam
+        # @return [Hash{String => Array<String>}]
+        attr_reader :messages
+
+        # @param messages [Hash{String => Array<String>}] at least one
+        def initialize(messages)
+          @messages = messages
+          param, (detail, *) = messages.first
+          super(param, detail)
+        end
+      end
+
+      # What a rule needs to read its value: the operator it is compared
+      # with (the request's, else the stored rule's, else the column default).
+      Context = Data.define(:operator)
+
+      # The shape of each column type the API writes.
+      BY_TYPE = { boolean: :boolean, string: :text, text: :text, integer: :integer }.freeze
+
+      # The attributes whose shape is not their column type's.
+      DECLARED = {
+        'allowed_ips' => :ip_list, 'requires_session_flag' => :flag,
+        'allowed_hours_start' => :hour, 'allowed_hours_end' => :hour,
+        'field_value' => :rule_value, 'permission_set_group_id' => :reference
+      }.freeze
+
+      # The shapes whose blank String ("") is no value (null): a condition
+      # or a reference is cleared with it.
+      BLANK_CLEARS = %i[ip_list flag hour reference].freeze
+
+      # Each shape's reader, (value, Context) → the value to store, or a
+      # Refusal (its message key under permission_forge.api.errors).
+      SHAPES = {
+        boolean: ->(value, _) { ParamShapes.boolean(value).then { |read| read.nil? ? Refusal.new('boolean_invalid') : read } },
+        text: ->(value, _) { value.is_a?(String) ? value : Refusal.new('text_shape') },
+        integer: ->(value, _) { whole_number?(value) ? value : Refusal.new('integer_shape') },
+        hour: ->(value, _) { whole_number?(value) ? value : Refusal.new('hour_shape') },
+        flag: ->(value, _) { value.is_a?(String) ? value : Refusal.new('flag_shape') },
+        ip_list: ->(value, _) { ip_list(value) },
+        rule_value: ->(value, context) { rule_value(value, context) },
+        reference: ->(value, _) { value },
+        as_is: ->(value, _) { value }
+      }.freeze
+
+      # A whole number as an hour or a count is sent: an Integer, or digits
+      # with an optional minus sign and surrounding white space.
+      WHOLE_NUMBER = /\A\s*-?\d+\s*\z/
+
+      module_function
+
+      # The `keys` of `attrs` it has, each read in its shape.
+      #
+      # @param attrs [ActionController::Parameters] the section (NUL bytes dropped)
+      # @param model [Class] the model the section writes
+      # @param keys [Array<Symbol, String>] the attributes the endpoint takes
+      # @param record [ActiveRecord::Base, nil] the record an update changes
+      #   (a rule's stored operator reads its value)
+      # @return [ActiveSupport::HashWithIndifferentAccess]
+      # @raise [Refused] naming every attribute of the wrong shape
+      def call(attrs, model, keys, record: nil)
+        context = Context.new(operator: operator_of(attrs, model, record))
+        read = keys.map(&:to_s).select { |key| attrs.key?(key) }.to_h { |key| [key, read_value(attrs[key], shape_of(model, key), context)] }
+        refused = read.select { |_, value| value.is_a?(Refusal) }
+        raise Refused, messages(refused) if refused.any?
+
+        read.with_indifferent_access
+      end
+
+      # One parameter outside a section (a copy's `name`) in `shape`; nil
+      # is no value.
+      #
+      # @raise [Refused] keyed by `key` for another shape
+      # @return [void]
+      def check!(key, value, shape)
+        read = value.nil? ? nil : SHAPES.fetch(shape).call(value, nil)
+        raise Refused, messages(key.to_s => read) if read.is_a?(Refusal)
+      end
+
+      # The shape `key` of `model` is read in: DECLARED, else its type's
+      # (BY_TYPE), else :as_is.
+      #
+      # @return [Symbol] a SHAPES key
+      def shape_of(model, key)
+        DECLARED.fetch(key.to_s) { BY_TYPE.fetch(model.type_for_attribute(key.to_s).type, :as_is) }
+      end
+
+      # The field-keyed messages of the Refusals.
+      def messages(refusals)
+        refusals.transform_values { |refusal| [I18n.t("permission_forge.api.errors.#{refusal.message}")] }
+      end
+
+      def read_value(value, shape, context)
+        value = nil if value == '' && BLANK_CLEARS.include?(shape)
+        return value if value.nil?
+
+        SHAPES.fetch(shape).call(value, context)
+      end
+
+      def operator_of(attrs, model, record)
+        operator = attrs['operator'] if attrs.key?('operator')
+        return operator if operator.is_a?(String)
+        return record.operator if record.respond_to?(:operator)
+
+        model.column_defaults['operator']
+      end
+
+      def whole_number?(value)
+        value.is_a?(Integer) || (value.is_a?(String) && value.match?(WHOLE_NUMBER))
+      end
+
+      # A String (commas, newlines or spaces between the entries) or a list
+      # of Strings, the entries joined with commas by the one parser
+      # (ActivationConditions). A list with no entry (`[]`, `[""]`, `" , "`)
+      # is refused rather than read as "no condition": null (or "") clears.
+      def ip_list(value)
+        return Refusal.new('ip_list_shape') unless value.is_a?(String) || (value.is_a?(Array) && value.all?(String))
+
+        PermissionForge::ActivationConditions.entries(value).join(',').presence || Refusal.new('ip_list_empty')
+      end
+
+      # A rule's value as the text the rule stores (see the module).
+      def rule_value(value, context)
+        return list_text(value, context.operator) if value.is_a?(Array)
+
+        scalar_text(value) || Refusal.new('field_value_shape')
+      end
+
+      # A list joined with commas, for an operator that takes several values;
+      # each element a scalar without a comma (the stored text is split at
+      # them: Operators::ValueTyping.split).
+      def list_text(value, operator)
+        typing = PermissionForge::Operators::ValueTyping
+        texts = value.map { |element| scalar_text(element) }
+        joinable = typing::SEVERAL.include?(typing::SHAPES[operator]) && texts.any? && texts.none? { |text| text.nil? || text.include?(',') }
+        joinable ? texts.join(',') : Refusal.new('field_value_shape')
+      end
+
+      # The text of a JSON scalar: a String as sent, a number as written
+      # (a fraction without an exponent: 1.5 → "1.5"), true / false as
+      # "true" / "false"; nil for anything else.
+      def scalar_text(value)
+        case value
+        when String then value
+        when Integer, true, false then value.to_s
+        when Float then BigDecimal(value.to_s).to_s('F') if value.finite?
+        end
+      end
+      private_class_method :messages, :read_value, :operator_of, :whole_number?, :ip_list, :rule_value, :list_text, :scalar_text
+    end
+  end
+end

data/app/controllers/concerns/permission_forge/api/pagination.rb

@@ -6,6 +6,10 @@ module PermissionForge
       # Beyond this the offset overflows the database's integer; the page is
       # empty long before.
       MAX_PAGE = (2**31) - 1
+      # What a page or a page size is: a positive whole number
+      # (ParamShapes#pf_integer_param reads it; "abc", "0", "-1", "2abc",
+      # 1.5 and a list are not one).
+      POSITIVE = (1..)
 
       private
 
@@ -34,16 +38,19 @@ module PermissionForge
         }
       end
 
-      # Anything that is not a number (a Hash, an Array) reads as page 1.
+      # params[:page] when it is a positive whole number (at most MAX_PAGE),
+      # else the first page.
       def current_page
-        params[:page].to_s.to_i.clamp(1, MAX_PAGE)
+        pf_integer_param(:page, default: 1, range: POSITIVE).clamp(1, MAX_PAGE)
       end
 
+      # params[:per_page] when it is a positive whole number, else
+      # config.api_default_per_page; never above config.api_max_per_page.
+      # A typo (`per_page=abc`), 0 or a negative number is the default page
+      # size, not a page of one row (through 0.14.1 they read as 1).
       def clamped_per_page
         config = PermissionForge.configuration
-        requested = params[:per_page]
-        requested = requested.nil? ? config.api_default_per_page : requested.to_s.to_i
-        requested.clamp(1, config.api_max_per_page)
+        pf_integer_param(:per_page, default: config.api_default_per_page, range: POSITIVE).clamp(1, config.api_max_per_page)
       end
     end
   end

data/app/controllers/concerns/permission_forge/api/response_renderer.rb

@@ -21,6 +21,20 @@ module PermissionForge
         end
       end
 
+      # One record and the cache outcome of the change that made or removed
+      # it (Cache::Outcome, as a bulk assignment answers it):
+      # `{ "data": { ... }, "meta": { "cache": { ... } } }`, the record by
+      # the serializer of its type (`permission_set_user`).
+      def render_record_with_cache(record, outcome, status:)
+        serializer_class = serializer_for(record.model_name.element.to_sym)
+        meta = { cache: outcome.to_h }
+        if ams_serializer?(serializer_class)
+          render json: record, serializer: serializer_class, root: :data, meta: meta, status: status
+        else
+          render json: { data: serializer_class.new(record).as_json, meta: meta }, status: status
+        end
+      end
+
       def render_collection(scope, serializer_class)
         paginator = PermissionForge.configuration.api_pagination_handler
         records = paginator ? paginate_scope(scope, paginator) : default_paginate_scope(scope)
@@ -35,7 +49,29 @@ module PermissionForge
       end
 
       def render_validation_errors(record)
-        render json: { error: { status: 422, messages: record.errors.messages } }, status: :unprocessable_entity
+        render_unprocessable(record.errors.messages)
+      end
+
+      # The one 422 shape: `messages` maps a field (a parameter, an attribute,
+      # or "base" when the error names none) to its messages, for validation
+      # errors and unreadable input alike.
+      def render_unprocessable(messages)
+        render json: { error: { status: 422, messages: messages } }, status: :unprocessable_entity
+      end
+
+      # An input error (ParamShapes::InvalidParam, a missing or malformed
+      # body section, Rails' own BadRequest) as field-keyed messages.
+      def render_input_error(error)
+        render_unprocessable(input_error_messages(error))
+      end
+
+      def input_error_messages(error)
+        case error
+        when PermissionForge::ParamShapes::InvalidParam then error.messages
+        when ActionController::ParameterMissing
+          { error.param.to_s => [I18n.t('permission_forge.api.errors.section_missing')] }
+        else { 'base' => [error.message] }
+        end
       end
 
       # Saves a record and renders the created resource or its validation errors.

data/app/controllers/concerns/permission_forge/api_authentication.rb

@@ -20,6 +20,13 @@ module PermissionForge
 
     # A refused request records api.auth_failed: who the host knows (the
     # audit actor resolver, the signed-in user), else unknown.
+    #
+    # api_auth answers whether the caller is authenticated: a falsy answer
+    # is a 401, so a client that refreshes its credentials on 401 does so.
+    # What an authenticated caller may change is the authorization lambdas'
+    # decision (403). The gem cannot know the host's scheme, so it sends no
+    # WWW-Authenticate of its own: one the lambda set on
+    # `controller.response.headers` is kept.
     def authenticate_api_request!
       auth_check = PermissionForge.configuration.api_auth
       if auth_check.nil?
@@ -28,8 +35,12 @@ module PermissionForge
       end
       return if auth_check.call(self)
 
-      audit_api_auth_failure('api_auth_denied', 403)
-      render json: { error: { status: 403, messages: I18n.t('permission_forge.api.errors.forbidden') } }, status: :forbidden
+      audit_api_auth_failure('api_auth_denied', 401)
+      # Runs before the request's locale is assigned (set_api_locale is a
+      # later callback): the 401 says it in the request's language too
+      # (through 0.14.1 always in the default locale).
+      set_api_locale
+      render json: { error: { status: 401, messages: I18n.t('permission_forge.api.errors.unauthorized') } }, status: :unauthorized
     end
 
     def audit_api_auth_failure(reason, status)

data/app/controllers/concerns/permission_forge/cache_confirmation.rb

@@ -2,7 +2,10 @@
 
 module PermissionForge
   # For admin actions that clear somebody's cached permissions: says what the
-  # cache store confirmed, instead of announcing success whatever happened.
+  # cache store confirmed, and when the store lives in this process only,
+  # instead of announcing success whatever happened. One Cache::Outcome
+  # (Cache::Report) is the datum, as in the rake tasks, the API and the
+  # audit events.
   #
   # @api private
   module CacheConfirmation
@@ -10,23 +13,51 @@ module PermissionForge
 
     private
 
-    # Whether the cache store confirmed every invalidation made in the block.
-    # The gem's own failure bookkeeping is asked, not the value of
+    # Measures the invalidations made in the block (Cache::Report.of). The
+    # gem's own failure bookkeeping is asked, not the value of
     # invalidate_permissions: host apps override that method.
-    def cache_confirmed?(&)
-      PermissionForge::Cache::Failure.none?(&)
+    #
+    # @return [PermissionForge::Cache::Outcome]
+    def cache_outcome(&)
+      PermissionForge::Cache::Report.of(&)
     end
 
     # The notice — or, when the cache store did not confirm that the cached
     # permissions are gone, the alert, which says the old ones may still be
-    # served. `keys` names both, under permission_forge.flash.people:
-    # `{ notice: :erased, alert: :erased_cache_kept }`.
+    # served (a confirmation not known yet, inside a transaction of the
+    # host's, is not a failure). `keys` names both, under
+    # permission_forge.flash.<controller_name>: `{ notice: :erased, alert: :erased_cache_kept }`.
+    # When the store lives in this process only (Outcome#process_local?) the
+    # text ends with flash.cache_process_local: other processes kept theirs.
     #
+    # @param outcome [PermissionForge::Cache::Outcome, Hash] an Outcome, or a service's `cache:`
     # @return [Hash] for redirect_to
-    def cache_flash(confirmed, keys, **)
-      kind = confirmed ? :notice : :alert
-      key = keys.fetch(kind)
-      { kind => t("permission_forge.flash.people.#{key}", default: key.to_s.humanize, **) }
+    def cache_flash(outcome, keys, **)
+      outcome = PermissionForge::Cache::Outcome.wrap(outcome)
+      kind = outcome.flash_kind
+      cache_scoped(outcome, kind => t("permission_forge.flash.#{controller_name}.#{keys.fetch(kind)}", **))
+    end
+
+    # The flash for a change whose message has no alert of its own (one
+    # assignment, a batch of edits): `text` as the notice, or — when the
+    # store did not confirm — as the alert, followed by
+    # flash.cache_not_confirmed; flash.cache_process_local as in #cache_flash.
+    #
+    # @param outcome [PermissionForge::Cache::Outcome]
+    # @param text [String] the translated notice
+    # @return [Hash] for redirect_to / pf_redirect
+    def cache_flash_text(outcome, text)
+      kind = outcome.flash_kind
+      text = "#{text} #{t('permission_forge.flash.cache_not_confirmed')}" if kind == :alert
+      cache_scoped(outcome, kind => text)
+    end
+
+    # `flash` with flash.cache_process_local appended when the store lives
+    # in this process only.
+    def cache_scoped(outcome, flash)
+      return flash unless outcome.process_local?
+
+      flash.transform_values { |text| "#{text} #{t('permission_forge.flash.cache_process_local')}" }
     end
   end
 end