current_scope 0.2.0

data/app/controllers/current_scope/application_controller.rb

@@ -0,0 +1,54 @@
+module CurrentScope
+  # Inherits from the host's controller (config.parent_controller) so the
+  # host's authentication — and its Context before_action — run first.
+  # The management UI is the place permissions are granted, so it cannot be
+  # gated by grantable permissions: only full_access subjects get in.
+  class ApplicationController < CurrentScope.config.parent_controller.constantize
+    # The read-only-while-impersonating gate, installed directly (not via Guard):
+    # this controller SKIPS the permission check, and mutations here — role,
+    # grant, and grid edits — are the highest-value surface to keep read-only
+    # while impersonating. Host stop-impersonation/sign-out/sign-in endpoints
+    # skip it with skip_before_action :current_scope_mutation_guard!.
+    include CurrentScope::MutationGuard
+
+    layout "current_scope/application"
+
+    # The engine's controllers are excluded from the grantable catalog; they
+    # answer to require_full_access! instead of the host's Guard gate.
+    skip_before_action :current_scope_check!, raise: false
+
+    before_action :require_full_access!
+
+    private
+
+    def require_full_access!
+      head :forbidden unless CurrentScope.resolver.full_access?(CurrentScope::Current.user)
+    end
+
+    def subject_class
+      @subject_class ||= CurrentScope.config.subject_class.constantize
+    end
+
+    # The submitted subject GIDs for a bulk-or-single action: the multi-select
+    # subject_gids[] when present, else the single subject_gid. Raw strings —
+    # pass through locate_subjects to resolve and enforce the subject boundary.
+    def submitted_subject_gids
+      gids = Array(params[:subject_gids]).select(&:present?)
+      gids = [ params[:subject_gid] ].compact if gids.empty?
+      gids
+    end
+
+    # Resolve subject GIDs to records, keeping ONLY instances of the configured
+    # subject_class. A crafted subject_gids[] pointing at some other model must
+    # never create an assignment row for a non-subject — the picker offers only
+    # subjects, so anything else is out of bounds. Dead/unknown GIDs drop out.
+    def locate_subjects(gids)
+      Array(gids).select(&:present?).filter_map do |gid|
+        record = GlobalID::Locator.locate(gid)
+        record if record.is_a?(subject_class)
+      rescue ActiveRecord::RecordNotFound, NameError
+        nil
+      end.uniq # duplicate subject_gids[] must count once (notice + audit accuracy)
+    end
+  end
+end

data/app/controllers/current_scope/events_controller.rb

@@ -0,0 +1,14 @@
+module CurrentScope
+  # Read-only view of the append-only audit ledger. Inherits the full-access
+  # gate and mutation guard from ApplicationController; there is no write path.
+  class EventsController < ApplicationController
+    PER_PAGE = 50
+
+    def index
+      @page = [ params[:page].to_i, 1 ].max
+      scope = Event.order(id: :desc)
+      @events = scope.limit(PER_PAGE).offset((@page - 1) * PER_PAGE)
+      @has_next_page = scope.offset(@page * PER_PAGE).exists?
+    end
+  end
+end

data/app/controllers/current_scope/role_assignments_controller.rb

@@ -0,0 +1,104 @@
+module CurrentScope
+  # Sets (or clears) a subject's single org-wide role.
+  class RoleAssignmentsController < ApplicationController
+    def create
+      subjects = locate_subjects(submitted_subject_gids)
+      if subjects.empty?
+        redirect_back_or_to subjects_path, alert: "No subjects selected."
+        return
+      end
+
+      clearing = params[:role_id].blank?
+
+      # One transaction for the whole bulk action: the UI presents it as a single
+      # operation, so a failure partway must not leave only the first subjects
+      # changed. All-or-nothing across assignments and their audit events. Count
+      # only the subjects that ACTUALLY changed so the notice can't over-report
+      # (a re-set to the same role, or a clear on a subject with no role, is a
+      # no-op and shouldn't be counted).
+      changed = 0
+      RoleAssignment.transaction do
+        subjects.each do |subject|
+          assignment = RoleAssignment.find_or_initialize_by(subject: subject)
+          prior_role = assignment.role # nil for a brand-new assignment
+          did = clearing ? clear_org_role(subject, assignment, prior_role) : set_org_role(subject, assignment, prior_role)
+          changed += 1 if did
+        end
+      end
+
+      # Return to wherever the action was invoked (the subjects page or a role's
+      # members page); falls back to subjects when there's no referrer.
+      redirect_back_or_to subjects_path, notice: org_notice(clearing, changed)
+    rescue ActiveRecord::RecordNotFound, NameError
+      redirect_back_or_to subjects_path, alert: "Couldn't set the org-wide role — a subject or role is no longer available."
+    end
+
+    # Remove ONE org-wide assignment by id — the path the members page uses to
+    # clean up an orphaned assignment whose subject was deleted (the subject-keyed
+    # clear on `create` can't target a subject that no longer resolves).
+    def destroy
+      assignment = RoleAssignment.find(params[:id])
+      subject = resolve_subject(assignment)
+      role_name = assignment.role.name
+
+      RoleAssignment.transaction do
+        assignment.destroy!
+        Event.record!(event: "org_role.removed", target: subject || assignment, details: { role: role_name })
+      end
+      redirect_back_or_to subjects_path, notice: "Org-wide role removed."
+    rescue ActiveRecord::RecordNotFound
+      redirect_back_or_to subjects_path, notice: "That org-wide role was already removed."
+    end
+
+    private
+
+    # The grantee, or nil when the subject was deleted or its type no longer
+    # resolves (an orphaned assignment) — the ledger row then targets the
+    # assignment itself rather than 500ing.
+    def resolve_subject(assignment)
+      assignment.subject
+    rescue ActiveRecord::RecordNotFound, NameError
+      nil
+    end
+
+    def org_notice(clearing, count)
+      return "No org-wide role changes." if count.zero?
+
+      verb = clearing ? "cleared" : "set"
+      count == 1 ? "Org-wide role #{verb}." : "Org-wide role #{verb} for #{count} subjects."
+    end
+
+    # Returns true when a role was actually cleared, false when there was nothing
+    # to clear (so the caller's count stays accurate).
+    def clear_org_role(subject, assignment, prior_role)
+      return false unless assignment.persisted? # nothing to clear ⇒ no event
+
+      RoleAssignment.transaction do
+        assignment.destroy!
+        Event.record!(event: "org_role.removed", target: subject, details: { role: prior_role.name })
+      end
+      true
+    end
+
+    # Returns true when the subject's role actually changed, false on a no-op
+    # re-set to the same role.
+    def set_org_role(subject, assignment, prior_role)
+      # Fetch the new role as its own object so `prior_role` (already loaded via
+      # the association) isn't mistaken for it after the update.
+      new_role = Role.find(params.expect(:role_id))
+      changed = prior_role.nil? || prior_role.id != new_role.id
+
+      RoleAssignment.transaction do
+        assignment.update!(role: new_role)
+        if prior_role.nil?
+          Event.record!(event: "org_role.assigned", target: subject, details: { role: new_role.name })
+        elsif prior_role.id != new_role.id
+          Event.record!(event: "org_role.changed", target: subject,
+                        details: { from: prior_role.name, to: new_role.name })
+        end
+        # same role re-set ⇒ no change ⇒ no event
+      end
+      changed
+    end
+  end
+end

data/app/controllers/current_scope/roles_controller.rb

@@ -0,0 +1,135 @@
+module CurrentScope
+  class RolesController < ApplicationController
+    def index
+      @roles = Role.order(:name)
+    end
+
+    def new
+      @role = Role.new
+    end
+
+    def create
+      @role = Role.new(role_params)
+      saved = false
+      Role.transaction do
+        saved = @role.save
+        # Fold the initial permission set into the create event — no separate
+        # grid-diff event for a brand-new role.
+        if saved
+          Event.record!(event: "role.created", target: @role,
+                        details: { name: @role.name, full_access: @role.full_access?,
+                                   permission_keys: @role.permission_keys })
+        end
+      end
+
+      if saved
+        redirect_to edit_role_path(@role), notice: "Role created."
+      else
+        render :new, status: :unprocessable_entity
+      end
+    end
+
+    def edit
+      @role = Role.find(params[:id])
+    end
+
+    # Who holds this role — the role-side complement to the subjects page. Org-wide
+    # holders (this role IS their one org-wide role) and per-record scoped holders,
+    # plus a capped list of subjects to add from here.
+    ADD_LIMIT = 100
+
+    def members
+      @role = Role.find(params[:id])
+      # No polymorphic includes: eager-loading a stale/renamed subject_type or
+      # resource_type raises NameError. Lazy-load per row and label defensively
+      # in the view (current_scope_holder_* helpers), like the audit ledger does.
+      @org_holders = RoleAssignment.where(role: @role).to_a
+      @scoped_holders = ScopedRoleAssignment.where(role: @role).to_a
+
+      # Exclude via a subquery, not a plucked Ruby array, so a role with many
+      # holders doesn't build a huge NOT IN bind list.
+      held = RoleAssignment.where(role: @role, subject_type: subject_class.name).select(:subject_id)
+      remaining = subject_class.where.not(id: held).order(:id)
+      @candidates = remaining.limit(ADD_LIMIT).to_a
+      @more_candidates = remaining.offset(ADD_LIMIT).exists?
+    end
+
+    def update
+      @role = Role.find(params[:id])
+      previous_name = @role.name
+      saved = false
+      Role.transaction do
+        saved = @role.update(role_params)
+        record_role_update(@role, previous_name) if saved
+      end
+
+      if saved
+        redirect_to roles_path, notice: "Role updated."
+      else
+        render :edit, status: :unprocessable_entity
+      end
+    end
+
+    def destroy
+      role = Role.find(params[:id])
+
+      if last_full_access?(role)
+        redirect_to roles_path,
+                    alert: "Refusing to delete the last full-access role — it would lock everyone out of this UI."
+        return
+      end
+
+      # Snapshot the cascade BEFORE destroy! — dependent: :destroy takes the
+      # assignments with the role, so they can't be read afterwards.
+      org_removed = role.role_assignments.includes(:subject).to_a
+      scoped_revoked = role.scoped_role_assignments.includes(:subject, :resource).to_a
+
+      Role.transaction do
+        role.destroy!
+        Event.record!(event: "role.deleted", target: role, details: { name: role.name })
+        org_removed.each do |a|
+          Event.record!(event: "org_role.removed", target: a.subject, details: { role: role.name })
+        end
+        scoped_revoked.each do |a|
+          Event.record!(event: "scoped_role.revoked", target: a.subject,
+                        details: { role: role.name, resource: helpers.current_scope_label(a.resource) })
+        end
+      end
+      redirect_to roles_path, notice: "Role deleted."
+    end
+
+    private
+
+    # One event per save: role.renamed when the name changed (carries old/new
+    # name AND the grid diff), else role.updated for a pure grid change. Emits
+    # nothing when neither the name nor the grid moved.
+    def record_role_update(role, previous_name)
+      diff = role.permission_keys_change || { added: [], removed: [] }
+      renamed = previous_name != role.name
+      return unless renamed || diff[:added].any? || diff[:removed].any?
+
+      details = { added: diff[:added], removed: diff[:removed] }
+      event = "role.updated"
+      if renamed
+        event = "role.renamed"
+        details.merge!(old_name: previous_name, new_name: role.name)
+      end
+      Event.record!(event: event, target: role, details: details)
+    end
+
+    def last_full_access?(role)
+      role.full_access? && !Role.where(full_access: true).where.not(id: role.id).exists?
+    end
+
+    def role_params
+      permitted = params.expect(role: [ :name, :description, :full_access, permission_keys: [] ])
+      # Grid group columns (CRUD checkboxes) submit "controller:group" tokens on
+      # a separate, optional channel — permitted leniently so a raw permission_keys
+      # post (no groups) still works. Expand them into action keys; the model's
+      # permission_keys= dedups and drops anything not in the catalog.
+      groups = params.fetch(:role, {}).permit(permission_groups: [])[:permission_groups]
+      permitted[:permission_keys] = Array(permitted[:permission_keys]) + PermissionGrid.new.expand(groups)
+      permitted
+    end
+  end
+end

data/app/controllers/current_scope/scoped_role_assignments_controller.rb

@@ -0,0 +1,159 @@
+module CurrentScope
+  # Grants/revokes a role on ONE specific record. `new` is a guided cascade
+  # (Role → Subject → Resource type → Record); `create` grants; `destroy`
+  # revokes. A record page can still deep-link straight to a target with:
+  #
+  #   current_scope.new_scoped_role_assignment_path(resource_gid: record.to_gid)
+  class ScopedRoleAssignmentsController < ApplicationController
+    # ponytail: record search scans only the first SCAN_CAP rows of a type and
+    # renders at most DISPLAY_LIMIT matches. current_scope_label is a Ruby
+    # method with no backing column, so the filter runs in Ruby (not SQL LIKE);
+    # a dedicated indexed label column is the upgrade path for large tables.
+    SCAN_CAP = 500
+    DISPLAY_LIMIT = 50
+    # Offer a search box (instead of listing every record) past this many.
+    SEARCH_THRESHOLD = 20
+
+    def new
+      @assignment = ScopedRoleAssignment.new
+      @roles = Role.order(:name)
+      @subjects = subject_class.order(:id)
+      @scopeable = CurrentScope.scopeable_resources
+      @bulk_subjects = resolve_bulk_subjects # [] unless a multi-select bulk grant
+
+      @resource = deep_linked_resource
+      @resource_type = resolve_type(params[:resource_type]) || @resource&.class
+      @searchable = searchable?(@resource_type)
+      @records = candidate_records(@resource_type, params[:q])
+    end
+
+    def create
+      resource = GlobalID::Locator.locate(params.expect(:resource_gid))
+      role = Role.find(params.expect(:role_id))
+      subjects = locate_subjects(submitted_subject_gids)
+      if subjects.empty?
+        redirect_to subjects_path, alert: "No subjects selected."
+        return
+      end
+
+      granted = 0
+      # One transaction for the whole bulk grant — all-or-nothing, like the
+      # org-wide sibling. A per-subject savepoint (grant_one) absorbs the
+      # concurrent-duplicate race without poisoning the outer transaction, while
+      # a genuine RecordInvalid rolls the entire batch back.
+      ScopedRoleAssignment.transaction do
+        subjects.each { |subject| granted += 1 if grant_one(subject, resource, role) }
+      end
+
+      redirect_to subjects_path, notice: grant_notice(granted, subjects.size)
+    rescue ActiveRecord::RecordInvalid => e
+      redirect_to subjects_path, alert: e.message
+    rescue ActiveRecord::RecordNotFound, NameError
+      redirect_to subjects_path,
+                  alert: "Couldn't grant that scoped role — the subject, role, or record is no longer available."
+    end
+
+    def destroy
+      assignment = ScopedRoleAssignment.find(params[:id])
+      subject, role = assignment.subject, assignment.role
+
+      ScopedRoleAssignment.transaction do
+        assignment.destroy!
+        Event.record!(event: "scoped_role.revoked", target: subject,
+                      details: { role: role.name, resource: assignment_resource_label(assignment) })
+      end
+      redirect_to subjects_path, notice: "Scoped role revoked."
+    rescue ActiveRecord::RecordNotFound
+      redirect_to subjects_path, notice: "That scoped role was already revoked."
+    end
+
+    private
+
+    # The scoped record may be deleted (nil) or its class renamed (NameError) by
+    # the time we revoke — label from the record when it's still there, else from
+    # the stored type/id, so the audit event never 500s on a stale reference.
+    def assignment_resource_label(assignment)
+      resource = assignment.resource
+      resource ? helpers.current_scope_label(resource) : "#{assignment.resource_type} ##{assignment.resource_id}"
+    rescue NameError, ActiveRecord::RecordNotFound
+      "#{assignment.resource_type} ##{assignment.resource_id}"
+    end
+
+    # Deep-link prefill: a record page links here with resource_gid. A stale
+    # link (deleted record → RecordNotFound, renamed class → NameError) must
+    # not 500 — fall back to the blank picker with a friendly alert.
+    def deep_linked_resource
+      GlobalID::Locator.locate(params[:resource_gid]) if params[:resource_gid].present?
+    rescue ActiveRecord::RecordNotFound, NameError
+      flash.now[:alert] = "That linked record is no longer available — pick one below."
+      nil
+    end
+
+    # Grant one scoped role inside its own savepoint. Returns true when a new
+    # grant was recorded, false when the subject already had it (or a concurrent
+    # grant won the race). A RecordInvalid propagates to roll the whole bulk back.
+    def grant_one(subject, resource, role)
+      ScopedRoleAssignment.transaction(requires_new: true) do
+        assignment = ScopedRoleAssignment.find_or_create_by!(subject: subject, resource: resource, role: role)
+        if assignment.previously_new_record?
+          Event.record!(event: "scoped_role.granted", target: subject,
+                        details: { role: role.name, resource: helpers.current_scope_label(resource) })
+          true
+        else
+          false
+        end
+      end
+    rescue ActiveRecord::RecordNotUnique
+      false # a concurrent grant slipped past the validation to the DB index — already done
+    rescue ActiveRecord::RecordInvalid => e
+      # A concurrent grant of the same triple usually trips the uniqueness
+      # VALIDATION first (RecordInvalid, not RecordNotUnique). Absorb only that
+      # case per-subject; any other validation failure rolls the whole batch back.
+      raise unless e.record.errors.of_kind?(:role_id, :taken)
+
+      false
+    end
+
+    # Resolve the bulk subject_gids for display (dead links and non-subject GIDs
+    # drop out — same boundary the grant enforces).
+    def resolve_bulk_subjects
+      locate_subjects(params[:subject_gids])
+    end
+
+    def grant_notice(granted, attempted)
+      return "Those subjects already have that scoped role." if granted.zero?
+      return "Scoped role granted." if granted == 1 && attempted == 1
+
+      "Scoped role granted to #{granted} #{'subject'.pluralize(granted)}."
+    end
+
+    # Only registered Scopeable types are resolvable from params — never
+    # constantize arbitrary visitor input.
+    def resolve_type(name)
+      CurrentScope.scopeable_resources.find { |model| model.name == name } if name.present?
+    end
+
+    def searchable?(klass)
+      klass.respond_to?(:count) && klass.count > SEARCH_THRESHOLD
+    end
+
+    def candidate_records(klass, query)
+      return unless klass.respond_to?(:limit) # tableless / nil type ⇒ nothing to pick
+
+      # A14: if the host model opts in with a class-level current_scope_searchable_scope,
+      # search via that indexed relation — no SCAN_CAP, no in-Ruby label filter.
+      if query.present? && klass.respond_to?(:current_scope_searchable_scope)
+        return klass.current_scope_searchable_scope(query).limit(DISPLAY_LIMIT).to_a
+      end
+
+      # Fallback: current_scope_label is a Ruby method with no backing column, so
+      # scan the first SCAN_CAP rows and filter the label in Ruby.
+      records = klass.limit(SCAN_CAP).to_a
+      if query.present?
+        needle = query.downcase
+        records = records.select { |record| helpers.current_scope_label(record).downcase.include?(needle) }
+      end
+      records.first(DISPLAY_LIMIT)
+    end
+  end
+end

data/app/controllers/current_scope/subjects_controller.rb

@@ -0,0 +1,57 @@
+module CurrentScope
+  class SubjectsController < ApplicationController
+    PER_PAGE = 50
+
+    # Identity columns searched by ?q=, in the same preference order as
+    # current_scope_subject_label's default chain. Intersected with the subject
+    # table's real column_names before use, so a query never spans a page.
+    SEARCH_COLUMNS = %w[email email_address name first_name last_name].freeze
+
+    def index
+      klass = CurrentScope.config.subject_class.constantize
+      @query = params[:q].to_s.strip
+      scope = filter_subjects(klass.order(:id), @query)
+
+      @page = [ params[:page].to_i, 1 ].max
+      @subjects = scope.limit(PER_PAGE).offset((@page - 1) * PER_PAGE)
+      @has_next_page = scope.offset(@page * PER_PAGE).exists?
+
+      @roles = Role.order(:name)
+      @assignments = RoleAssignment.where(subject: @subjects)
+                                   .index_by { |a| [ a.subject_type, a.subject_id ] }
+      @scoped = ScopedRoleAssignment.where(subject: @subjects)
+                                    .includes(:role, :resource)
+                                    .group_by { |a| [ a.subject_type, a.subject_id ] }
+    end
+
+    private
+
+    # Server-side search across the subject's human-identity columns, so a query
+    # matches EVERY subject rather than only the current page's client-side
+    # filter. Columns come from the table's real column_names (never interpolate
+    # user input as a column name), so this is injection-safe. A Proc
+    # subject_label can't be expressed in SQL; when the model exposes none of the
+    # searchable columns this returns the scope unfiltered and the per-page
+    # client filter remains the only narrowing.
+    def filter_subjects(scope, query)
+      return scope if query.blank?
+
+      columns = subject_search_columns(scope.klass)
+      return scope if columns.empty?
+
+      conn    = scope.klass.connection
+      clause  = columns.map { |c| "LOWER(#{conn.quote_column_name(c)}) LIKE ?" }.join(" OR ")
+      # ponytail: % / _ in the query pass through as LIKE wildcards — fine for an
+      # admin search; add ESCAPE handling if that ever surprises someone.
+      scope.where(clause, *([ "%#{query.downcase}%" ] * columns.size))
+    end
+
+    def subject_search_columns(klass)
+      configured = CurrentScope.config.subject_label
+      candidates = []
+      candidates << configured.to_s if configured.is_a?(Symbol)
+      candidates.concat(SEARCH_COLUMNS)
+      candidates.uniq.select { |c| klass.column_names.include?(c) }
+    end
+  end
+end

data/app/helpers/current_scope/application_helper.rb

@@ -0,0 +1,72 @@
+module CurrentScope
+  module ApplicationHelper
+    # Best-effort human label for any host subject/resource. Prefers a record's
+    # own current_scope_label (the Scopeable mixin gives every pickable model
+    # one) so the label a model declares is the label shown everywhere — the
+    # picker, the chips, and the ledger (see Event.label_for) all agree.
+    def current_scope_label(record)
+      return "(none)" if record.nil?
+      return record.current_scope_label if record.respond_to?(:current_scope_label)
+
+      name = record.try(:name) || record.try(:email) || record.try(:title)
+      name || "#{record.class.name} ##{record.id}"
+    end
+
+    # Human label for a subject (user/account), honouring config.subject_label
+    # so a host on UUID keys can show email or a full name instead of an
+    # opaque id. Falls back to the best-effort current_scope_label.
+    def current_scope_subject_label(subject)
+      return "(none)" if subject.nil?
+
+      # A configured label that resolves to nil/blank (e.g. :email on a subject
+      # with no email yet) must not render as an empty row — fall through to the
+      # default human-identifier chain rather than showing "".
+      configured = configured_subject_label(subject)
+      return configured if configured
+
+      # Default: a subject is a person, so prefer human identifiers over a
+      # generic "Class #id" — including when the model includes Scopeable, whose
+      # current_scope_label is id-based. Covers `email` and Rails 8 auth's
+      # `email_address`. Config overrides this entirely.
+      full_name = [ subject.try(:first_name), subject.try(:last_name) ].compact.join(" ").presence
+      # .presence on each identifier: a stored empty/whitespace email ("") is
+      # truthy in Ruby and would otherwise short-circuit to a blank label.
+      subject.try(:email).presence || subject.try(:email_address).presence ||
+        subject.try(:name).presence || full_name || current_scope_label(subject)
+    end
+
+    # The configured subject_label (Symbol or Proc) applied to a subject, or nil
+    # when unset or when it resolves to a blank value.
+    def configured_subject_label(subject)
+      label = CurrentScope.config.subject_label
+      if label.respond_to?(:call)
+        label.call(subject).to_s.presence
+      elsif label && subject.respond_to?(label)
+        subject.public_send(label).to_s.presence
+      end
+    end
+
+    # Members-list labels that survive a stale/renamed polymorphic type — a
+    # removed subject or resource class must not 500 the page; fall back to
+    # "Type #id" the way the audit ledger does.
+    def current_scope_holder_subject_label(assignment)
+      current_scope_subject_label(assignment.subject)
+    rescue NameError, ActiveRecord::RecordNotFound
+      "#{assignment.subject_type} ##{assignment.subject_id}"
+    end
+
+    def current_scope_holder_resource_label(scoped_assignment)
+      current_scope_label(scoped_assignment.resource)
+    rescue NameError, ActiveRecord::RecordNotFound
+      "#{scoped_assignment.resource_type} ##{scoped_assignment.resource_id}"
+    end
+
+    # Best-effort label for a stored GID string (event actor/subject). Falls
+    # back to the raw GID when the record is gone — the ledger outlives the
+    # identities it names.
+    def current_scope_gid_label(gid)
+      record = GlobalID::Locator.locate(gid)
+      record ? current_scope_label(record) : gid
+    end
+  end
+end

data/app/models/current_scope/application_record.rb

@@ -0,0 +1,5 @@
+module CurrentScope
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/current_scope/current.rb

@@ -0,0 +1,50 @@
+module CurrentScope
+  # The ambient authorization context. Request- and job-scoped: Rails resets
+  # CurrentAttributes around every unit of execution, so the subject can never
+  # leak between requests, jobs, or test examples.
+  #
+  # Two identities live here:
+  #   - user  — the EFFECTIVE subject every permission check reads.
+  #   - actor — the REAL principal behind the request (the pretender's
+  #             `true_user`). It falls back to `user`, so attribution always
+  #             reads `actor` with no nil branch. They differ only while
+  #             impersonating: actor = the admin, user = the impersonated subject.
+  class Current < ActiveSupport::CurrentAttributes
+    # request_id is correlation-only metadata the audit recorder stamps onto
+    # each event; nil when the host hasn't set it. Additive — no reader override.
+    attribute :user, :actor, :request_id
+
+    # Per-request memo for the resolver's org-role lookup. A view with N
+    # permission-gated elements calls the gate N times, each otherwise re-running
+    # the same `RoleAssignment.find_by(subject:)`; caching it here collapses that
+    # to one query. Request/job-scoped like everything on CurrentAttributes, so
+    # it never leaks across requests, and invalidated on any org-role write (see
+    # RoleAssignment) so a grant-then-check within one request is never stale.
+    attribute :org_role_cache
+
+    # Falls back to the effective subject, so actor is never nil when user is
+    # set — callers attribute to `actor` without a nil branch.
+    def actor
+      super || user
+    end
+
+    # Memoize the org-role lookup for `subject` for the rest of this request/job.
+    # Keyed by subject so a check that spans several subjects stays correct.
+    # Caches nil (no role) too, so a repeated "no grant" check is one query, not N.
+    def memoized_org_role(subject)
+      return yield if subject.nil?
+
+      cache = (self.org_role_cache ||= {})
+      key = [ subject.class.name, subject.id ]
+      return cache[key] if cache.key?(key)
+
+      cache[key] = yield
+    end
+
+    # Drop the memo — called on any org-role write so a later check in the same
+    # request sees the change.
+    def reset_org_role_cache
+      self.org_role_cache = nil
+    end
+  end
+end