permission_forge 0.14.1

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # @api private
+  module ApiAuthentication
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :verify_api_enabled!
+      before_action :authenticate_api_request!
+    end
+
+    private
+
+    def verify_api_enabled!
+      return if PermissionForge.configuration.api_enabled
+
+      head :not_found
+    end
+
+    # A refused request records api.auth_failed: who the host knows (the
+    # audit actor resolver, the signed-in user), else unknown.
+    def authenticate_api_request!
+      auth_check = PermissionForge.configuration.api_auth
+      if auth_check.nil?
+        audit_api_auth_failure('api_auth_not_configured', 401)
+        return head(:unauthorized)
+      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
+    end
+
+    def audit_api_auth_failure(reason, status)
+      PermissionForge::Audit::RequestContext.refused(self, 'api.auth_failed', source: 'api',
+                                                                              data: { 'reason' => reason, 'status' => status })
+    end
+  end
+end

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

@@ -0,0 +1,97 @@
+module PermissionForge
+  # Asks `config.admin_assignment_authorization` before a change to who holds
+  # a Permission Set or belongs to a Permission Set Group — in the HTML admin
+  # and in the API (there after `api_assignment_authorization`, which keeps
+  # its own signature). Segregation of duties lives in the lambda, e.g. no
+  # self-assignment:
+  #
+  #   config.admin_assignment_authorization = lambda { |controller, target, user_ids, action|
+  #     admin = PermissionForge.current_user
+  #     admin&.admin? && !user_ids.include?(admin.id)
+  #   }
+  #
+  # The lambda receives (controller, target, user_ids, action):
+  #   controller — the admin or API controller handling the request
+  #   target     — the PermissionForge::PermissionSet or ::PermissionSetGroup
+  #   user_ids   — Array of the people concerned, cast to the user model's
+  #                primary-key type (Integers for bigint keys)
+  #   action     — one of ACTIONS
+  # A truthy answer allows; nil (no lambda) allows everything. A refused
+  # request changes nothing, so it writes no change event; a raising lambda
+  # raises (the request fails, nothing changes).
+  #
+  # @api private
+  module AssignmentAuthorization
+    # :grant / :revoke a Permission Set, :change_expiry of an assignment,
+    # :review (access review "Keep"), :add_member / :remove_member of a group.
+    ACTIONS = %i[grant revoke change_expiry review add_member remove_member].freeze
+
+    private
+
+    # @param target [PermissionForge::PermissionSet, PermissionForge::PermissionSetGroup]
+    # @param user_ids [Array, Object] the people concerned
+    # @param action [Symbol] one of ACTIONS
+    # @return [Boolean]
+    def pf_assignment_allowed?(target, user_ids, action)
+      raise ArgumentError, "unknown assignment action #{action.inspect}" unless ACTIONS.include?(action)
+
+      hook = PermissionForge.configuration.admin_assignment_authorization
+      return true unless hook
+
+      hook.call(self, target, pf_cast_user_ids(user_ids), action) ? true : false
+    end
+
+    # HTML admin: true (after redirecting with an alert) when any of the
+    # targets is refused, so the caller returns before changing anything.
+    # The refusal is recorded (admin.auth_failed).
+    def pf_assignment_refused?(targets, user_ids, action, path)
+      refused = Array(targets).find { |target| !pf_assignment_allowed?(target, user_ids, action) }
+      return false unless refused
+
+      pf_audit_assignment_refusal('admin.auth_failed', refused, user_ids, action)
+      redirect_to path, alert: t('permission_forge.flash.assignment_not_authorized')
+      true
+    end
+
+    # API: true (after rendering a 403) when the target is refused. The
+    # refusal is recorded (api.auth_failed).
+    def pf_assignment_refused_api?(target, user_ids, action)
+      return false if pf_assignment_allowed?(target, user_ids, action)
+
+      pf_audit_assignment_refusal('api.auth_failed', target, user_ids, action)
+      render_not_authorized(I18n.t('permission_forge.api.errors.assignment_not_authorized'))
+      true
+    end
+
+    # The locked set that refuses a change to its holders because the change
+    # widens access — adding to a granting set, removing from a Muting one,
+    # an end date moved the matching way (Admin::EditableLock.widening_lock);
+    # nil when the change may go ahead.
+    #
+    # @param change [Symbol] :grant, :revoke or :change_expiry (with from:/to:)
+    # @return [PermissionForge::PermissionSet, nil]
+    def pf_widening_lock(permission_set, change, **expiry)
+      PermissionForge::Admin::EditableLock.widening_lock(permission_set, change, **expiry)
+    end
+
+    # HTML admin: true (after redirecting with the lock's alert and recording
+    # admin.lock_refused) when `locked` (a #pf_widening_lock answer) is a set.
+    def pf_widening_refused?(locked, path)
+      return false unless locked
+
+      alert = locked.is_muting ? t('permission_forge.flash.locked_widening_muting') : t('permission_forge.flash.locked_widening')
+      pf_reject_locked!(locked, path, alert: alert)
+    end
+
+    # pf_audit_refused: the including base controller's (HTML or API).
+    def pf_audit_assignment_refusal(event, target, user_ids, action)
+      payload = PermissionForge::Audit::Refusals.assignment(target, user_ids, action: action,
+                                                                              hook: 'admin_assignment_authorization')
+      pf_audit_refused(event, **payload)
+    end
+
+    def pf_cast_user_ids(user_ids)
+      PermissionForge::Admin::PeopleDirectory::Ids.cast(user_ids)
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+module PermissionForge
+  # The HTML admin's gate in front of the audit log: the log page, one
+  # event, the exports, and the audit tabs of a person and a Permission Set.
+  # Audit::LogAccess decides (config.audit_log_authorization); a refusal is
+  # recorded once per request (admin.auth_failed, reason
+  # audit_log_not_authorized) and answered with a 403 — a page that says so,
+  # or nothing for a file. A refused request is never recorded as viewed or
+  # exported (Audit::AuditedViews records 2xx responses only).
+  #
+  # @api private
+  module AuditLogGate
+    REFUSAL_REASON = 'audit_log_not_authorized'.freeze
+
+    private
+
+    # @return [Boolean] whether this request may read the audit log
+    def pf_audit_log_allowed?
+      return @pf_audit_log_allowed if defined?(@pf_audit_log_allowed)
+
+      @pf_audit_log_allowed = PermissionForge::Audit::LogAccess.allowed?(self)
+      pf_audit_refused('admin.auth_failed', data: { 'reason' => REFUSAL_REASON }) unless @pf_audit_log_allowed
+      @pf_audit_log_allowed
+    end
+
+    # before_action: the refusal, unless the log may be read.
+    def pf_require_audit_log!
+      pf_render_audit_refusal unless pf_audit_log_allowed?
+    end
+
+    # The audit tab of a page (people#show, permission_sets#show) and its
+    # CSV are the audit log too; the other tabs need no permission.
+    def pf_audit_tab_allowed?
+      return true unless @tab == 'audit' || request.format.csv?
+
+      pf_audit_log_allowed?
+    end
+
+    # Refused on a page with tabs: the page renders with the refusal on its
+    # audit tab (403); a file is not sent.
+    def pf_refuse_audit_tab
+      return head(:forbidden) unless request.format.html?
+
+      @audit_refused = true
+      render :show, status: :forbidden
+    end
+
+    def pf_render_audit_refusal
+      if request.format.html?
+        render 'permission_forge/shared/audit_refused', status: :forbidden
+      else
+        head :forbidden
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+module PermissionForge
+  # HTTP Basic authentication for the admin screens, driven by `config.http_basic_auth_*`;
+  # the engine's controllers include it.
+  #
+  # @api public
+  module BasicAuthentication
+    extend ActiveSupport::Concern
+
+    # A username is stored as the actor label of an event: a varchar(255).
+    AUDIT_USERNAME_LIMIT = 255
+
+    included do
+      before_action :authenticate_by_http_basic
+    end
+
+    private
+
+    def authenticate_by_http_basic
+      return unless http_basic_auth_enabled?
+
+      unless http_basic_auth_configured?
+        audit_http_basic_failure('basic_auth_not_configured')
+        return head(:unauthorized)
+      end
+
+      authenticate_or_request_with_http_basic('PermissionForge') do |given_user, given_password|
+        verified = http_basic_credentials_match?(given_user, given_password)
+        verified ? remember_http_basic_user : audit_http_basic_failure('invalid_credentials')
+        verified
+      end
+    end
+
+    def http_basic_credentials_match?(given_user, given_password)
+      ActiveSupport::SecurityUtils.secure_compare(given_user, http_basic_auth_credentials[:user].to_s) &
+        ActiveSupport::SecurityUtils.secure_compare(given_password, http_basic_auth_credentials[:password].to_s)
+    end
+
+    # The verified username names the actor of the request's audit events
+    # (Audit::ActorResolver) — the configured one, never what was typed.
+    def remember_http_basic_user
+      request.env[PermissionForge::Audit::ActorResolver::BASIC_AUTH_ENV] = http_basic_auth_credentials[:user].to_s
+    end
+
+    # Records admin.auth_failed when credentials were sent: the username as
+    # typed (capped, valid UTF-8), never the password. A browser's first
+    # request, which sends none, is the challenge, not a failure.
+    def audit_http_basic_failure(reason)
+      return unless ActionController::HttpAuthentication::Basic.has_basic_credentials?(request)
+
+      username = ActionController::HttpAuthentication::Basic.user_name_and_password(request).first
+      PermissionForge::Audit::RequestContext.refused(
+        self, 'admin.auth_failed', source: 'admin_ui',
+                                   actor: { type: 'basic_auth', label: audit_username(username) },
+                                   data: { 'reason' => reason }
+      )
+    end
+
+    def audit_username(username)
+      username.to_s.dup.force_encoding(Encoding::UTF_8).scrub.delete("\u0000")[0, AUDIT_USERNAME_LIMIT]
+    end
+
+    def http_basic_auth_enabled?
+      PermissionForge.configuration.http_basic_auth_enabled
+    end
+
+    def http_basic_auth_configured?
+      http_basic_auth_credentials.values.all?(&:present?)
+    end
+
+    def http_basic_auth_credentials
+      {
+        user: PermissionForge.configuration.http_basic_auth_user,
+        password: PermissionForge.configuration.http_basic_auth_password
+      }
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  # For admin actions that clear somebody's cached permissions: says what the
+  # cache store confirmed, instead of announcing success whatever happened.
+  #
+  # @api private
+  module CacheConfirmation
+    extend ActiveSupport::Concern
+
+    private
+
+    # Whether the cache store confirmed every invalidation made in the block.
+    # 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?(&)
+    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 }`.
+    #
+    # @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, **) }
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+module PermissionForge
+  # How the admin screens and the admin API verify a mutating request. Rails
+  # 8.2 checks the browser's Sec-Fetch-Site header, and `load_defaults 8.2`
+  # selects `:header_only`, which lets a plain-HTTP request that carries no
+  # such header through without any check — a forged request from a browser
+  # that does not send it, or to an app served over HTTP. The engine's
+  # controllers use `:header_or_legacy_token` whatever the host chose: the
+  # header decides when the browser sends it (same-origin and same-site pass
+  # without a token, cross-site is refused), and without it the authenticity
+  # token is required, as on every earlier Rails. Rails before 8.2 has no
+  # such choice and always checks the token.
+  #
+  # @api private
+  module ForgeryProtection
+    extend ActiveSupport::Concern
+
+    STRATEGY = :header_or_legacy_token
+
+    class_methods do
+      # The engine's verification strategy as protect_from_forgery options,
+      # empty where Rails offers no choice. Each controller calls
+      # protect_from_forgery itself with its own `with:`, so the call stays
+      # visible (and Brakeman sees it).
+      def pf_forgery_strategy
+        respond_to?(:forgery_protection_verification_strategy) ? { using: STRATEGY } : {}
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+module PermissionForge
+  # The admin screens answer HTML, plus the exports an action declares
+  # (pf_exports). Any other Accept header or extension — a scanner's
+  # application/json, text/csv on a form — is answered in HTML: the admin
+  # has no other templates, and a failing form must not end in a missing
+  # template (a 500). Runs first, before anything renders.
+  #
+  # @example
+  #   pf_exports %i[csv json], only: %i[index holdings]
+  #
+  # @api private
+  module HtmlFormat
+    extend ActiveSupport::Concern
+
+    included do
+      # action name => the formats it answers besides HTML
+      class_attribute :pf_export_formats, instance_writer: false, default: {}.freeze
+      prepend_before_action :pf_negotiate_html
+    end
+
+    class_methods do
+      # @param formats [Array<Symbol>] e.g. %i[csv]
+      # @param only [Symbol, Array<Symbol>] the actions that export them
+      def pf_exports(formats, only:)
+        exports = Array(only).to_h { |action| [action.to_s, formats.map(&:to_s).freeze] }
+        self.pf_export_formats = pf_export_formats.merge(exports).freeze
+      end
+    end
+
+    private
+
+    # The first acceptable format that is HTML or an export of the action
+    # (as respond_to would choose), else HTML.
+    def pf_negotiate_html
+      exports = pf_export_formats.fetch(action_name, [])
+      chosen = request.formats.map { |format| format.symbol.to_s }.find { |name| name == 'html' || exports.include?(name) }
+      request.format = (chosen || 'html').to_sym
+    end
+  end
+end

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

@@ -0,0 +1,87 @@
+module PermissionForge
+  # Request parameters in the shape an action expects. A crafted request
+  # that sends a String or an Array where a Hash is expected, or a Hash where
+  # an id or a date is, gets a 4xx (or the value is ignored) — never a 500.
+  #
+  # Every attribute hash the admin and the API write from (pf_require_hash,
+  # pf_hash_param) and every typed text (pf_text_param) comes without NUL
+  # bytes: PostgreSQL refuses one in text (a 500), the other databases would
+  # store it. The one place for both surfaces; `reason` keeps its own
+  # cleaning (Audit::ColumnValues).
+  #
+  # @api private
+  module ParamShapes
+    # Typed text: see #pf_text_param.
+    #
+    # @return [String]
+    def self.text(value)
+      value.is_a?(String) ? value.delete("\0").strip : ''
+    end
+
+    # `value` with NUL bytes removed from every String in it, however deep.
+    #
+    # @return [Object] a new Parameters / Array, or the value itself
+    def self.without_nul(value)
+      case value
+      when String then value.delete("\0")
+      when Array then value.map { |item| without_nul(item) }
+      when ActionController::Parameters then value.transform_values { |item| without_nul(item) }
+      else value
+      end
+    end
+
+    private
+
+    # params.require(key), which must be a Hash of attributes.
+    #
+    # @raise [ActionController::ParameterMissing] when it is missing, empty or
+    #   not a Hash (400; the API answers 422)
+    def pf_require_hash(key)
+      value = params.require(key)
+      raise ActionController::ParameterMissing, key unless value.is_a?(ActionController::Parameters)
+
+      ParamShapes.without_nul(value)
+    end
+
+    # params[key] when it is a Hash of attributes (without NUL bytes), else
+    # an empty one.
+    def pf_hash_param(key)
+      value = params[key]
+      value.is_a?(ActionController::Parameters) ? ParamShapes.without_nul(value) : ActionController::Parameters.new
+    end
+
+    # Typed text from params[key]: a String without NUL bytes (they cut a
+    # quoted SQL literal short, and PostgreSQL refuses them in text) and
+    # without surrounding white space; '' for anything else.
+    def pf_text_param(key)
+      ParamShapes.text(params[key])
+    end
+
+    # params[:tab] when it is one of `tabs`, else nil (a Hash or an Array
+    # would reach url_for as unpermitted parameters).
+    def pf_tab_param(tabs)
+      tab = params[:tab]
+      tab if tabs.include?(tab)
+    end
+
+    # The Integer ids in params[key] (one value or a list); anything that is
+    # not digits is dropped.
+    def pf_id_list(key)
+      Array.wrap(params[key]).filter_map { |value| PermissionForge::Admin::RecordId.cast(value) }
+    end
+
+    # The time params[key] names, nil when it is blank.
+    #
+    # @raise [ActionController::BadRequest] for a value that is no time:
+    #   a date that cannot be read must never become "no end date"
+    def pf_time_param(key)
+      value = params[key]
+      return nil if value.blank?
+
+      time = Time.zone.parse(value.to_s) if value.is_a?(String)
+      time || raise(ActionController::BadRequest, "#{key} is not a time")
+    rescue ArgumentError
+      raise ActionController::BadRequest, "#{key} is not a time"
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+module PermissionForge
+  # The admin screens and the admin API serve one tenant at a time. With
+  # tenancy on (config.tenant_model) a request that reaches them with no
+  # current tenant is refused — acts_as_tenant scopes nothing without one, so
+  # it would read and change every tenant's Permission Sets, assignments and
+  # audit log — unless config.admin_tenantless_access = :allow. The refusal
+  # is recorded through the including controller's pf_audit_refused
+  # (admin.auth_failed / api.auth_failed, reason tenant_missing) and answered
+  # with a 403: JSON from the API, plain text from the admin screens (their
+  # layout's navigation and counts would read across tenants).
+  #
+  # The including controller registers `before_action :pf_require_tenant`
+  # after authentication and its locale: an unauthenticated request still
+  # gets its 401, the refusal is in the request's language, and a host base
+  # controller's own callbacks (which set the tenant) have run.
+  #
+  # @api public
+  module TenantRequired
+    REFUSAL_REASON = 'tenant_missing'.freeze
+    API_SOURCE = 'api'.freeze
+
+    private
+
+    def pf_require_tenant
+      return unless pf_tenant_missing?
+
+      api = self.class::AUDIT_SOURCE == API_SOURCE
+      pf_audit_refused(api ? 'api.auth_failed' : 'admin.auth_failed', data: { 'reason' => REFUSAL_REASON })
+      if api
+        render json: { error: { status: 403, messages: I18n.t('permission_forge.api.errors.tenant_required') } },
+               status: :forbidden
+      else
+        render plain: I18n.t('permission_forge.errors.tenant_required'), status: :forbidden
+      end
+    end
+
+    def pf_tenant_missing?
+      config = PermissionForge.configuration
+      config.tenant_enabled? && !config.admin_tenantless_access_allowed? && PermissionForge.ambient_tenant.nil?
+    end
+  end
+end

data/app/controllers/permission_forge/api/audit_events_controller.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module PermissionForge
+  module Api
+    # Read-only view of the audit log. Gated by api_enabled and api_auth (the
+    # base controller) and then by config.audit_log_authorization
+    # (Audit::LogAccess). Rows are tenant-scoped by the model.
+    class AuditEventsController < BaseController
+      before_action :authorize_audit_log!
+
+      rescue_from PermissionForge::Audit::EventQuery::Invalid do |error|
+        render json: { error: { status: 422, messages: error.errors } }, status: :unprocessable_entity
+      end
+
+      def index
+        render_collection(PermissionForge::Audit::EventQuery.call(params), serializer_for(:audit_event))
+      end
+
+      def show
+        render_record(find_record(PermissionForge::AuditEvent), serializer_for(:audit_event))
+      end
+
+      private
+
+      def authorize_audit_log!
+        return if PermissionForge::Audit::LogAccess.allowed?(self)
+
+        pf_audit_refused('api.auth_failed', data: { 'reason' => 'audit_log_not_authorized' })
+        render_not_authorized
+      end
+    end
+  end
+end