current_scope 0.2.0

data/lib/current_scope/mutation_guard.rb

@@ -0,0 +1,55 @@
+module CurrentScope
+  # The read-only-while-impersonating gate. A SEPARATE before_action from the
+  # permission check, on purpose: the engine's management UI does
+  # skip_before_action :current_scope_check!, and a gate folded into that check
+  # would exempt the highest-value surface (grid/role/grant mutations). Guard
+  # includes this so the gate runs BEFORE the permission check; the engine
+  # ApplicationController includes it directly so skipping the permission check
+  # never skips the gate.
+  #
+  # An impersonated session is read-only by default: any non-GET/HEAD request is
+  # denied while a real actor stands behind a different effective subject. The
+  # endpoints that MUST run while impersonating — a host's stop-impersonation,
+  # sign-out, and sign-in actions — opt out with:
+  #
+  #   skip_before_action :current_scope_mutation_guard!
+  #
+  # (Method spoofing is not a concern: Rack::MethodOverride only upgrades POST,
+  # and mutating actions are verb-pinned by routing.)
+  module MutationGuard
+    extend ActiveSupport::Concern
+
+    included do
+      before_action :current_scope_mutation_guard!
+      rescue_from CurrentScope::AccessDenied, with: :current_scope_denied
+    end
+
+    private
+
+    def current_scope_mutation_guard!
+      return if request.get? || request.head?
+      return if CurrentScope.config.allow_mutations_while_impersonating
+      return unless current_scope_impersonating?
+
+      raise CurrentScope::AccessDenied.new(
+        "#{controller_path}##{action_name}", reason: :impersonation_gate
+      )
+    end
+
+    # A real actor stands behind a distinct effective subject (act-as). Read
+    # from the ambient context directly, so the gate holds even where the
+    # Permissions helpers are not mixed in.
+    def current_scope_impersonating?
+      user = CurrentScope::Current.user
+      user.present? && CurrentScope::Current.actor != user
+    end
+
+    # Denials render forbidden and surface the machine-readable reason on the
+    # response so refusals are diagnosable by clients and tests.
+    def current_scope_denied(exception = nil)
+      reason = exception.respond_to?(:reason) ? exception.reason : nil
+      response.headers["X-Current-Scope-Reason"] = reason.to_s if reason
+      head :forbidden
+    end
+  end
+end

data/lib/current_scope/permission_catalog.rb

@@ -0,0 +1,33 @@
+module CurrentScope
+  # Derives the permission set from the host's routes: one permission per
+  # controller#action pair. There is no table to maintain — add a controller
+  # and its actions appear in the grid on next boot/reload.
+  class PermissionCatalog
+    def keys
+      @keys ||= derive
+    end
+
+    # { "reports" => ["approve", "create", ...], ... } for the role-editor grid.
+    def grouped
+      keys.group_by { |key| key.split("#").first }
+          .transform_values { |ks| ks.map { |k| k.split("#").last } }
+    end
+
+    def include?(key)
+      keys.include?(key)
+    end
+
+    private
+
+    def derive
+      Rails.application.routes.routes.filter_map { |route|
+        controller = route.defaults[:controller]
+        action = route.defaults[:action]
+        next unless controller && action
+        next if CurrentScope.config.excluded_controllers.any? { |re| controller.match?(re) }
+
+        "#{controller}##{action}"
+      }.uniq.sort
+    end
+  end
+end

data/lib/current_scope/permission_grid.rb

@@ -0,0 +1,90 @@
+module CurrentScope
+  # Presents the route-derived permission catalog as an ALIGNED matrix for the
+  # role editor: fixed columns, one row per controller, blank cells where a
+  # controller doesn't route a column's actions (never a shifted cell).
+  #
+  # By default the columns are CRUD groups (config.permission_grid_groups):
+  # ticking one grants every routed action in the group, so the RESTful form
+  # actions fold into their mutation (new→create, edit→update) and index+show
+  # read as one. Actions outside any group (e.g. "approve") get their own
+  # column. With groups set to nil/{} every raw action becomes its own column —
+  # still aligned.
+  class PermissionGrid
+    Column = Struct.new(:label, :actions, :group, keyword_init: true)
+    Cell   = Struct.new(:blank, :group, :name, :value, :checked, :partial, :granted_keys, keyword_init: true)
+
+    def initialize(catalog: CurrentScope.catalog, groups: CurrentScope.config.permission_grid_groups)
+      @grouped = catalog.grouped # { "controller" => ["action", ...] }
+      @groups  = groups || {}
+    end
+
+    def controllers
+      @grouped.keys.sort
+    end
+
+    # Ordered columns: config groups that apply to at least one controller (in
+    # config order), then leftover actions not covered by any group (sorted).
+    def columns
+      grouped = @groups.filter_map do |label, actions|
+        Column.new(label: label, actions: actions, group: true) if any_controller_has?(actions)
+      end
+      grouped + leftover_actions.map { |action| Column.new(label: action, actions: [ action ], group: false) }
+    end
+
+    # One cell for (controller, column) against a role's granted key set.
+    # Blank when the controller routes none of the column's actions. Otherwise a
+    # checkbox.
+    #
+    # A GROUP cell is only `checked` when EVERY routed action is granted — a
+    # partial group is rendered unchecked+indeterminate and its existing keys are
+    # preserved verbatim via hidden inputs (see the edit view). This is the
+    # escalation guard: a checked group token expands to the whole group on save,
+    # so treating "some granted" as checked would silently promote a partial
+    # grant to a full one just by re-saving the role. `granted_keys` carries the
+    # exact subset to round-trip for a partial cell.
+    def cell(controller, column, granted)
+      routed = column.actions & actions_for(controller)
+      return Cell.new(blank: true) if routed.empty?
+
+      keys = routed.map { |action| "#{controller}##{action}" }
+      present_keys = keys.select { |key| granted.include?(key) }
+      partial = present_keys.any? && present_keys.size < keys.size
+      Cell.new(
+        blank: false,
+        group: column.group,
+        name:  column.group ? "role[permission_groups][]" : "role[permission_keys][]",
+        value: column.group ? "#{controller}:#{column.label}" : keys.first,
+        checked: column.group ? (present_keys.any? && !partial) : present_keys.any?,
+        partial: partial,
+        granted_keys: partial ? present_keys : []
+      )
+    end
+
+    # Expand submitted "controller:group" tokens into routed permission keys.
+    # Unknown groups/controllers and unrouted actions drop out.
+    def expand(tokens)
+      Array(tokens).flat_map do |token|
+        controller, label = token.to_s.split(":", 2)
+        actions = @groups[label]
+        next [] if actions.nil?
+
+        (actions & actions_for(controller)).map { |action| "#{controller}##{action}" }
+      end
+    end
+
+    def actions_for(controller)
+      @grouped[controller] || []
+    end
+
+    private
+
+    def any_controller_has?(actions)
+      @grouped.values.any? { |routed| routed.intersect?(actions) }
+    end
+
+    def leftover_actions
+      grouped = @groups.values.flatten.uniq
+      (@grouped.values.flatten.uniq - grouped).sort
+    end
+  end
+end

data/lib/current_scope/permissions.rb

@@ -0,0 +1,57 @@
+module CurrentScope
+  # The portable authorization mixin. Works anywhere — controllers, views,
+  # components, POROs — because the subject comes from the ambient
+  # CurrentScope::Current context rather than being threaded through calls.
+  # Everything delegates to the one resolver, so a view can never disagree
+  # with the controller gate.
+  #
+  #   allowed_to?(:approve, report)          # key derived from the record
+  #   allowed_to?(:create, Report)           # class works for collection actions
+  #   allowed_to?("admin/reports#approve")   # explicit full key
+  #   allowed_to?(:index, controller: "reports")
+  module Permissions
+    def allowed_to?(action, record = nil, controller: nil)
+      controller ||= controller_path if respond_to?(:controller_path)
+      CurrentScope.allowed?(action, subject: current_scope_user, record: record,
+        controller_path: controller, actor: current_scope_actor)
+    end
+
+    # The list-side companion to allowed_to?: "which records of `model` may the
+    # effective subject act on?". Same grants, keys, and fail-closed rules as
+    # the gate, so a list can't drift from the per-record decision. Returns a
+    # chainable relation (.where/.order/.page on it). `permission` defaults to
+    # the model's index context and accepts a bare action or a full key.
+    #
+    #   scope_for(Project)                 # projects#index — what a list shows
+    #   scope_for(Report, permission: :approve)
+    #   scope_for(Report, permission: "admin/reports#approve")
+    def scope_for(model, permission: nil)
+      # Derive the key exactly like allowed_to? — including controller_path, so a
+      # namespaced controller's list resolves to the same key as its gate
+      # (admin/reports#index, not reports#index) and the two never drift.
+      controller = controller_path if respond_to?(:controller_path)
+      CurrentScope.scope_for(
+        subject: current_scope_user,
+        model: model,
+        permission: CurrentScope.permission_key(permission || :index, record: model, controller_path: controller)
+      )
+    end
+
+    def current_scope_user
+      CurrentScope::Current.user
+    end
+
+    # The REAL actor behind the request (never nil when a subject is set — it
+    # falls back to the subject). Read this for attribution, not Current.
+    def current_scope_actor
+      CurrentScope::Current.actor
+    end
+
+    # True only while a distinct real actor stands behind the effective
+    # subject (act-as). Views use it as the read-only-state signal.
+    def impersonating?
+      CurrentScope::Current.user.present? &&
+        CurrentScope::Current.actor != CurrentScope::Current.user
+    end
+  end
+end

data/lib/current_scope/resolver.rb

@@ -0,0 +1,171 @@
+module CurrentScope
+  # The decision point. Every allow/deny question in the system routes through
+  # here, in a fixed order:
+  #
+  #   1. SoD veto      — the record's initiator can never perform an SoD action
+  #                      on it. Reads two identities: the effective subject and
+  #                      (under sod_identity :either) the real actor behind an
+  #                      impersonated session. Overrides everything, incl. full_access.
+  #   2. full_access   — the subject's org-wide role grants all permissions,
+  #                      present and future.
+  #   3. org-wide role — the role's permission set includes this permission.
+  #   4. scoped role   — a role held on THIS record grants the permission.
+  #   5. default-deny  — nothing granted means denied.
+  class Resolver
+    INITIATOR_METHOD = :current_scope_initiator
+    # Host-defined per-record opt-in for break-glass. Absent ⇒ never bypassed
+    # (fail-closed, no raise — unlike a missing initiator, absence here is
+    # unambiguous).
+    BYPASS_METHOD = :current_scope_sod_bypassed?
+
+    # Public contract: boolean. `actor` is the REAL principal behind the
+    # request (defaults to the subject — no impersonation); it only widens the
+    # SoD veto under config.sod_identity == :either.
+    def allow?(subject:, permission:, record: nil, actor: nil)
+      decide(subject: subject, permission: permission, record: record, actor: actor).first
+    end
+
+    # Internal decision: returns [allowed_bool, reason_or_nil]. The reason is a
+    # machine-readable cause the Guard surfaces: :sod_veto / :no_grant on a
+    # denial, and :sod_bypassed on the one AUDITED allow (break-glass). Ordinary
+    # allows carry nil. The resolver — shared across threads — holds no
+    # per-decision state; the reason rides in the return tuple, not on self.
+    def decide(subject:, permission:, record: nil, actor: nil)
+      return [ false, :no_grant ] if subject.nil?
+
+      case sod_decision(subject: subject, actor: actor, permission: permission, record: record)
+      when :veto   then return [ false, :sod_veto ]
+      when :bypass then return [ true, :sod_bypassed ] # break-glass: privileged, audited override
+      end
+
+      role = org_role(subject)
+      return [ true, nil ] if role&.full_access?
+      return [ true, nil ] if role&.grants?(permission)
+      return [ true, nil ] if scoped_grant?(subject: subject, permission: permission, record: record)
+
+      [ false, :no_grant ]
+    end
+
+    # The subject's one org-wide role. Memoized per request (via Current) so the
+    # many gate checks a single request makes don't each re-query — the decision
+    # is identical, only the lookup is cached, keeping the resolver a pure
+    # decision function over its inputs.
+    def org_role(subject)
+      CurrentScope::Current.memoized_org_role(subject) do
+        RoleAssignment.find_by(subject: subject)&.role
+      end
+    end
+
+    def full_access?(subject)
+      !!(subject && org_role(subject)&.full_access?)
+    end
+
+    # The list-side complement to allow?: "which records of `model` may this
+    # subject act on?". Reads the SAME org + scoped grants the gate reads, so a
+    # host list can never drift from the per-record decision. Fail-closed (nil
+    # subject / no grant → none) and flat — no parent/child cascade. SoD does
+    # NOT apply: it vetoes record-targeted actions, not list membership.
+    def scope_for(subject:, model:, permission:)
+      return model.none if subject.nil?
+
+      role = org_role(subject)
+      return model.all if role&.full_access? || role&.grants?(permission)
+
+      # Records on which the subject holds a scoped role that grants the key.
+      # Query the polymorphic base_class (what scoped grants store), not the
+      # passed model's name — otherwise scope_for(STISubclass) returns nothing
+      # while the per-record gate (also keyed on base_class) would allow it. The
+      # `model.where` still applies STI's own type predicate, so a subclass query
+      # can't over-list sibling-subclass rows. An empty subquery yields an empty
+      # (still chainable) relation.
+      model.where(
+        id: ScopedRoleAssignment
+              .where(subject: subject, resource_type: model.base_class.name, role_id: roles_granting(permission))
+              .select(:resource_id)
+      )
+    end
+
+    private
+
+    # Role ids that satisfy `permission`: full_access (grants everything) or an
+    # explicit grant of the key. The one place "does this role grant it?" is
+    # expressed for scoped grants — shared by the gate and scope_for.
+    def roles_granting(permission)
+      Role.where(full_access: true)
+          .or(Role.where(id: RolePermission.where(permission_key: permission).select(:role_id)))
+    end
+
+    # The separation-of-duties outcome for this decision: :none (no conflict, or
+    # not an SoD action), :veto (the initiator is acting on their own record and
+    # the veto stands), or :bypass (a conflict exists but break-glass lifts it).
+    # Pure — reads only; the audit write for a :bypass happens at the Guard.
+    def sod_decision(subject:, actor:, permission:, record:)
+      action = permission.split("#").last
+      return :none unless CurrentScope.config.sod_actions.include?(action)
+      # No veto without an actual record instance (collection actions get nil,
+      # class-form checks like allowed_to?(:approve, Report) get the class).
+      return :none unless record.respond_to?(:new_record?)
+
+      # SoD is a structural guarantee — "cannot determine the initiator" must
+      # never mean "permit". A record type where SoD genuinely doesn't apply
+      # declares the hook returning nil.
+      unless record.respond_to?(INITIATOR_METHOD, true)
+        raise ConfigurationError,
+              "#{record.class.name}##{INITIATOR_METHOD} is not defined, but " \
+              "\"#{permission}\" is a separation-of-duties action (config.sod_actions). " \
+              "Define #{INITIATOR_METHOD} on #{record.class.name} (return nil to exempt " \
+              "a record), or remove \"#{action}\" from config.sod_actions."
+      end
+
+      initiator = record.send(INITIATOR_METHOD)
+      return :none if initiator.blank?
+
+      # The subject can never approve their own record. Under :either, neither
+      # can a real actor who initiated it while impersonating a different
+      # subject — impersonation must not become a self-approval loophole. Not
+      # impersonating (actor == subject) collapses both checks to the same test.
+      actor ||= subject
+      conflict = initiator == subject ||
+        (CurrentScope.config.sod_identity == :either && actor != subject && initiator == actor)
+      return :none unless conflict
+
+      sod_bypassed?(record: record, initiator: initiator) ? :bypass : :veto
+    end
+
+    # Break-glass: does an audited, privileged override lift the veto for this
+    # record? All three must hold, live: the config switch is on, the record's
+    # host hook opts in, and the INITIATOR (the identity the veto fired on —
+    # KTD-2, so impersonation can't launder it) holds the bypass permission.
+    def sod_bypassed?(record:, initiator:)
+      return false unless CurrentScope.config.allow_sod_bypass
+
+      # Re-entrancy is bounded ONLY because the bypass permission isn't itself an
+      # SoD action (KTD-5) — the inner allowed? below returns at the SoD step
+      # without recursing. Enforce that invariant loudly rather than trusting the
+      # host to honor the doc comment: a bypass action in sod_actions would
+      # recurse to a SystemStackError.
+      bypass_action = CurrentScope.config.sod_bypass_permission.to_s.split("#").last
+      if CurrentScope.config.sod_actions.include?(bypass_action)
+        raise ConfigurationError,
+              "config.sod_bypass_permission (#{CurrentScope.config.sod_bypass_permission.inspect}) is the " \
+              "action #{bypass_action.inspect}, which is also in config.sod_actions. The bypass permission " \
+              "must not be an SoD action — it would recurse. Remove #{bypass_action.inspect} from sod_actions."
+      end
+
+      # Absent hook ⇒ this type never breaks glass (fail-closed, no raise).
+      return false unless record.respond_to?(BYPASS_METHOD, true) && record.send(BYPASS_METHOD)
+
+      CurrentScope.allowed?(CurrentScope.config.sod_bypass_permission, subject: initiator, record: record)
+    end
+
+    def scoped_grant?(subject:, permission:, record:)
+      # `record` may be a class (allowed_to?(:create, Report)) — classes can't
+      # hold scoped grants, only persisted records can.
+      return false unless record.respond_to?(:new_record?) && record.persisted?
+
+      ScopedRoleAssignment
+        .where(subject: subject, resource: record, role_id: roles_granting(permission))
+        .exists?
+    end
+  end
+end

data/lib/current_scope/scopeable.rb

@@ -0,0 +1,38 @@
+module CurrentScope
+  # Include CurrentScope::Scopeable to make a model pickable in the scoped-role
+  # assignment UI's type dropdown. BROWSE-ONLY — it does NOT gate access: any
+  # model is still a valid GlobalID scoped-role target whether or not it opts in.
+  #
+  # The `included` hook self-registers the class by NAME (stored as a string and
+  # resolved lazily) so dev-mode class reloading never pins a stale constant;
+  # the engine rebuilds the registry on every to_prepare.
+  module Scopeable
+    extend ActiveSupport::Concern
+
+    included do
+      CurrentScope.register_scopeable(name) if name
+    end
+
+    # Default label for the picker. Defined as an ordinary instance method so a
+    # host that provides its own current_scope_label simply overrides it — the
+    # host class sits ahead of this module in the ancestor chain.
+    def current_scope_label
+      "#{model_name.human} ##{id}"
+    end
+
+    # OPTIONAL indexed search for the scoped-role picker. current_scope_label is
+    # a Ruby method with no backing column, so by default the picker scans the
+    # first 500 rows and filters the label in Ruby. Define this class method to
+    # search via indexed SQL instead — it receives the query term and must
+    # return an ActiveRecord::Relation:
+    #
+    #   class Project < ApplicationRecord
+    #     include CurrentScope::Scopeable
+    #     def self.current_scope_searchable_scope(term)
+    #       where("name ILIKE ?", "%#{term}%")
+    #     end
+    #   end
+    #
+    # No default is provided — the host knows which column is indexed.
+  end
+end

data/lib/current_scope/test_helpers.rb

@@ -0,0 +1,53 @@
+module CurrentScope
+  # Test support for host apps:
+  #
+  #   include CurrentScope::TestHelpers
+  #
+  #   with_current_user(users(:alice)) do
+  #     assert component_allows_approve?
+  #   end
+  #
+  #   with_current_user(users(:bob), actor: users(:admin)) do   # act-as
+  #     assert impersonating?
+  #   end
+  #
+  # CurrentAttributes resets between examples, so nothing set here can leak.
+  module TestHelpers
+    # Snapshot/restore the RAW attributes rather than using Current.set: the
+    # actor reader falls back to user, and Object#with (which set uses) would
+    # snapshot that fallback and restore a stale actor. Saving the underlying
+    # hash restores the true prior state.
+    def with_current_user(user, actor: nil)
+      # dup: on Rails 8.0 `attributes` returns the LIVE hash, so without a copy
+      # the assignments below would mutate our own snapshot.
+      previous = CurrentScope::Current.attributes.dup
+      CurrentScope::Current.user = user
+      CurrentScope::Current.actor = actor
+      yield
+    ensure
+      # Version-robust restore: `attributes = previous` clears absent keys on
+      # Rails 8.1 but NOT on 8.0 (leaving the block's user set), so reset first,
+      # then re-apply the snapshot. Works identically on the whole >= 8.0 floor.
+      CurrentScope::Current.reset
+      previous.each { |name, value| CurrentScope::Current.public_send(:"#{name}=", value) }
+    end
+
+    # Seed a real org-wide grant for request/system specs. Unlike
+    # with_current_user (which only sets Current.user in-process, and is
+    # overwritten by Context's before_action on a real request), this persists a
+    # RoleAssignment row that survives the request cycle, so a host can test its
+    # own controllers behind the gate. It does NOT authenticate — the host still
+    # signs the subject in through its own auth. Bang-suffixed like the engine's
+    # other DB-mutating helpers (seed_defaults!, Event.record!). Returns the
+    # assignment.
+    def grant_role!(subject, role:)
+      CurrentScope::RoleAssignment.create!(subject: subject, role: role)
+    end
+
+    # The scoped-grant companion: seed a role held on ONE specific record.
+    # Returns the scoped assignment.
+    def grant_scoped_role!(subject, role:, record:)
+      CurrentScope::ScopedRoleAssignment.create!(subject: subject, role: role, resource: record)
+    end
+  end
+end

data/lib/current_scope/version.rb

@@ -0,0 +1,3 @@
+module CurrentScope
+  VERSION = "0.2.0"
+end

data/lib/current_scope.rb

@@ -0,0 +1,168 @@
+require "current_scope/version"
+require "current_scope/configuration"
+require "current_scope/permission_catalog"
+require "current_scope/permission_grid"
+require "current_scope/resolver"
+require "current_scope/permissions"
+require "current_scope/context"
+require "current_scope/scopeable"
+require "current_scope/mutation_guard"
+require "current_scope/guard"
+require "current_scope/gating_tripwire"
+require "current_scope/engine"
+
+module  CurrentScope
+  # Raised when the resolver denies an action gated by Guard (or when the
+  # management UI is accessed without a full-access role). Carries an optional
+  # machine-readable reason (:sod_veto, :no_grant, :impersonation_gate).
+  class AccessDenied < StandardError
+    attr_reader :reason
+
+    def initialize(message = nil, reason: nil)
+      super(message)
+      @reason = reason
+    end
+  end
+
+  # Raised when the host is wired up wrong (missing hook, bad config). Always
+  # raised loudly — an authorization library must never turn a configuration
+  # mistake into a silent allow or an undiagnosable deny.
+  class ConfigurationError < StandardError; end
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    def resolver
+      @resolver ||= Resolver.new
+    end
+
+    def catalog
+      @catalog ||= PermissionCatalog.new
+    end
+
+    def reset_catalog!
+      @catalog = nil
+    end
+
+    # Models that opted into the scoped-role picker via CurrentScope::Scopeable.
+    # Stored as class-name strings and resolved lazily so dev-mode reloading
+    # never pins a stale constant. Rebuilt from scratch on every engine
+    # to_prepare (see reset_scopeable_registry!).
+    def scopeable_registry
+      @scopeable_registry ||= Set.new
+    end
+
+    def register_scopeable(model_name)
+      scopeable_registry << model_name.to_s
+    end
+
+    def scopeable_resources
+      scopeable_registry.map(&:constantize).sort_by(&:name)
+    end
+
+    def reset_scopeable_registry!
+      @scopeable_registry = Set.new
+    end
+
+    # The single entry point behind every allowed_to? call.
+    # `action` is either a full permission key ("admin/reports#approve") or a
+    # bare action name resolved against `record`'s route key, falling back to
+    # `controller_path`.
+    def allowed?(action, subject:, record: nil, controller_path: nil, actor: nil)
+      resolver.allow?(
+        subject: subject,
+        permission: permission_key(action, record: record, controller_path: controller_path),
+        record: record,
+        actor: actor
+      )
+    end
+
+    # The list-side companion to allowed?. Returns a chainable relation of the
+    # records of `model` the subject may act on under `permission` — same
+    # grants, same fail-closed rules as the per-record gate. `permission` is a
+    # resolved key ("projects#index"); the mixin derives the default.
+    def scope_for(subject:, model:, permission:)
+      resolver.scope_for(subject: subject, model: model, permission: permission)
+    end
+
+    def permission_key(action, record: nil, controller_path: nil)
+      action = action.to_s
+      return action if action.include?("#")
+
+      if record.respond_to?(:model_name)
+        route_key = record.model_name.route_key
+        # When the current controller handles this record type (possibly under
+        # a namespace — admin/reports for a Report), its path is the key the
+        # Guard enforces, so prefer it: the view must agree with the gate.
+        return "#{controller_path}##{action}" if controller_path&.split("/")&.last == route_key
+
+        return "#{route_key}##{action}"
+      end
+      return "#{controller_path}##{action}" if controller_path
+
+      raise ArgumentError,
+            "cannot derive a permission key for #{action.inspect} — pass a record, " \
+            "a full \"controller#action\" string, or call from a controller/view"
+    end
+
+    # Impersonation boundary events. The impersonated identity is an EXPLICIT
+    # argument (not read from the ambient pair): at act-as START the ambient
+    # actor still equals the effective user — Current re-resolves next request —
+    # so an ambient-only recorder would lose who was impersonated. Call these
+    # from the host's start/stop-impersonation endpoints.
+    def record_impersonation_started!(subject)
+      require_actor_method!
+      Event.record!(event: "impersonation.started", target: subject)
+    end
+
+    def record_impersonation_stopped!(subject)
+      require_actor_method!
+      Event.record!(event: "impersonation.stopped", target: subject)
+    end
+
+    # Creates the two baseline roles every install needs: an Owner with
+    # full_access (present and future permissions) and a Member baseline.
+    # Call from db/seeds.rb.
+    def seed_defaults!
+      Role.find_or_create_by!(name: "Owner") { |r| r.full_access = true }
+      Role.find_or_create_by!(name: "Member")
+    end
+
+    # Bootstrap the first admin: assign a role (default: the full_access Owner)
+    # to `subject` as its one org-wide role. Idempotent — re-running sets the
+    # same subject's org role to `role` rather than creating a duplicate (which
+    # the one-role-per-subject uniqueness would reject anyway). Backs the
+    # `current_scope:grant` rake task, so a fresh install doesn't need a console.
+    def grant!(subject, role: nil)
+      seed_defaults!
+      role ||= Role.find_by!(name: "Owner")
+      RoleAssignment.find_or_initialize_by(subject: subject).tap { |a| a.update!(role: role) }
+    end
+
+    private
+
+    # A2: the boundary events are the one place a host declares it is actually
+    # impersonating. If actor_method is unset there, the entire act-as security
+    # model is silently inert — so fail LOUD instead of recording an
+    # impersonation with no real actor behind it. (The permission path can't
+    # detect this: with actor_method nil, actor falls back to user, so
+    # impersonating? is always false and a per-request check would nag every
+    # RBAC-only host. This seam only fires when the host declares intent.)
+    def require_actor_method!
+      return unless config.actor_method.nil?
+
+      raise ConfigurationError,
+            "impersonation boundary event recorded while config.actor_method is unset. " \
+            "Act-as security is inert without it: the read-only-while-impersonating " \
+            "MutationGuard never engages, the SoD :either veto can't fire, and audit rows " \
+            "are attributed to the impersonated subject instead of the real actor. Set " \
+            "config.actor_method to the controller method that returns the real actor."
+    end
+  end
+end