current_scope 0.5.0

data/app/controllers/current_scope/application_controller.rb

@@ -0,0 +1,96 @@
+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
+
+    # Raises rather than rendering, so the engine's front door lands in the same
+    # current_scope_denied path as every other denial and gets the reason header
+    # for free. It used to `head :forbidden` here — the one denial in the gem
+    # that sat outside that machinery, and so the one with no reason and no body
+    # (#23). MutationGuard's rescue_from catches this from a before_action.
+    #
+    # Who is denied is unchanged: the full_access? check is byte-for-byte what
+    # it was. Only how the refusal is surfaced changed.
+    def require_full_access!
+      return if CurrentScope.resolver.full_access?(CurrentScope::Current.user)
+
+      key = "#{controller_path}##{action_name}"
+      raise CurrentScope::AccessDenied.new(
+        key,
+        reason: :not_full_access,
+        permission: key,
+        subject: CurrentScope::Current.user
+      )
+    end
+
+    # The engine's UI is the one place a rendered denial belongs: the admin is
+    # looking at a browser, and "blank page" is not an answer to "why can't I get
+    # in?". Overrides ONLY the body — the reason header is still written by
+    # current_scope_denied, which stays the single place that knows about it.
+    #
+    # ONLY for :not_full_access. This concern rescues EVERY AccessDenied raised
+    # in this controller, and the other one that fires here is the impersonation
+    # gate — whose subject usually DOES have full access and is refused for an
+    # entirely different reason. Telling them they need a full-access role is a
+    # confidently wrong answer, which is worse than the blank page this fix
+    # replaces. Every other reason falls through to the bodyless default, i.e.
+    # exactly what it did before this change.
+    #
+    # HTML only: the page is a full HTML document, so a client that asked for
+    # anything else gets the bodyless 403 rather than markup under a content
+    # type it did not ask for.
+    #
+    # layout: false — the console layout is a sidebar of links to areas this
+    # subject cannot open. Offering them reads as "you're in" and then refuses
+    # every click.
+    def current_scope_render_denied(reason = nil)
+      return super unless reason == :not_full_access && request.format.html?
+
+      render "current_scope/shared/access_denied", status: :forbidden, layout: false
+    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,190 @@
+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).
+      #
+      # Lock full-access holders inside the same transaction as the writes so
+      # concurrent clears cannot both observe "another holder remains" and then
+      # both proceed to zero holders.
+      changed = 0
+      refused = false
+      RoleAssignment.transaction do
+        lock_full_access_org_holders!
+
+        if would_remove_last_full_access_holders?(subjects, clearing: clearing)
+          refused = true
+        else
+          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
+      end
+
+      if refused
+        redirect_back_or_to subjects_path,
+                            alert: "Refusing to remove the last full-access org-wide assignment — " \
+                                   "it would lock everyone out of this UI. Grant full access to " \
+                                   "another subject first, then retry."
+        return
+      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
+      refused = false
+      RoleAssignment.transaction do
+        # Lock FA state BEFORE the target assignment so order matches create/
+        # role demote/delete (FA roles → FA holders → target row). Locking the
+        # assignment first inverted that order and could deadlock.
+        lock_full_access_org_holders!
+        assignment = RoleAssignment.lock.find(params[:id])
+        subject = resolve_subject(assignment)
+        role_name = assignment.role.name
+
+        if last_full_access_org_assignment?(assignment)
+          refused = true
+        else
+          assignment.destroy!
+          Event.record!(event: "org_role.removed", target: subject || assignment, details: { role: role_name })
+        end
+      end
+
+      if refused
+        redirect_back_or_to subjects_path,
+                            alert: "Refusing to remove the last full-access org-wide assignment — " \
+                                   "it would lock everyone out of this UI. Grant full access to " \
+                                   "another subject first, then retry."
+        return
+      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.current_scope_resolved_record("subject")
+    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
+
+    # True when this assignment is a live full_access org holder and no other
+    # full_access org assignment exists. Orphan rows (deleted subject → nil)
+    # must not permanently block cleanup of the last FA assignment.
+    def last_full_access_org_assignment?(assignment)
+      return false unless assignment.role&.full_access?
+      return false if resolve_subject(assignment).nil?
+
+      !full_access_org_assignments.where.not(id: assignment.id).exists?
+    end
+
+    # True when applying clear (or reassign to a non-full_access role) to these
+    # subjects would leave zero full_access org holders.
+    def would_remove_last_full_access_holders?(subjects, clearing:)
+      holders = full_access_org_assignments.to_a
+      return false if holders.empty?
+
+      affected_ids = holders.select { |a| subjects.any? { |s| same_subject?(a, s) } }.map(&:id)
+      return false if affected_ids.empty?
+
+      unless clearing
+        new_role = Role.find_by(id: params[:role_id])
+        return false if new_role&.full_access?
+      end
+
+      remaining = holders.reject { |a| affected_ids.include?(a.id) }
+      remaining.empty?
+    end
+
+    def full_access_org_assignments
+      RoleAssignment.joins(:role).where(current_scope_roles: { full_access: true })
+    end
+
+    # Lock full-access holder rows (and their roles) so concurrent remove/demote
+    # paths serialize on the same set the precheck reads. Call only inside a
+    # transaction. Prefer locking by id after a join pluck — FOR UPDATE with
+    # joins is adapter-fragile.
+    def lock_full_access_org_holders!
+      Role.where(full_access: true).lock.load
+      ids = full_access_org_assignments.pluck(:id)
+      RoleAssignment.where(id: ids).lock.load if ids.any?
+    end
+
+    def same_subject?(assignment, subject)
+      # Match the polymorphic storage name the subjects page uses (not only
+      # base_class.name — hosts can customize polymorphic_name).
+      # to_s on both: subject_id is a string column (#151) while a record keyed on
+      # an integer answers 1, so a raw == silently never matches.
+      assignment.subject_type == subject.class.polymorphic_name &&
+        assignment.subject_id.to_s == subject.id.to_s
+    end
+
+    # Returns true when a role was actually cleared, false when there was nothing
+    # to clear (so the caller's count stays accurate). Atomicity comes from
+    # create's outer bulk transaction — only called from inside it. (No inner
+    # transaction: without requires_new it would be a bare yield, and it isn't
+    # wanted — a failure anywhere rolls back the whole batch by design.)
+    def clear_org_role(subject, assignment, prior_role)
+      return false unless assignment.persisted? # nothing to clear ⇒ no event
+
+      assignment.destroy!
+      Event.record!(event: "org_role.removed", target: subject, details: { role: prior_role.name })
+      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
+
+      # Atomicity comes from create's outer bulk transaction (see clear_org_role).
+      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
+      changed
+    end
+  end
+end

data/app/controllers/current_scope/roles_controller.rb

@@ -0,0 +1,256 @@
+module CurrentScope
+  class RolesController < ApplicationController
+    def index
+      # Includes for delete-confirm holder counts (cascade warning).
+      @roles = Role.order(:name).includes(:role_assignments, :scoped_role_assignments)
+    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 blanket polymorphic includes: stale subject_type/resource_type
+      # NameErrors at preload. Org holders stay lazy; scoped resources use the
+      # safe per-type preload (unresolvable types stay unloaded → inert label).
+      @org_holders = RoleAssignment.where(role: @role).to_a
+      @scoped_holders = ScopedRoleAssignment.where(role: @role).includes(role: :role_permissions).to_a
+      ScopedRoleAssignment.preload_resolvable_resources!(@scoped_holders)
+
+      # Still a subquery, not a plucked array: every subject holds exactly one
+      # org-wide role, so a default role is held by the WHOLE user table and a
+      # plucked NOT IN would carry one bind per subject. The cast is what makes it
+      # work now that subject_id is a string column (#151) while subject_class
+      # keys on a bigint — PostgreSQL refuses that comparison outright rather than
+      # coercing. Cast the candidate side, so the stored value is never altered.
+      held = RoleAssignment.where(role: @role, subject_type: subject_class.polymorphic_name)
+                           .select(:subject_id)
+      remaining = subject_class.where.not(
+        Arel::Nodes::In.new(candidate_key_as_text, held.arel.ast)
+      ).order(:id)
+      @candidates = remaining.limit(ADD_LIMIT).to_a
+      @more_candidates = remaining.offset(ADD_LIMIT).exists?
+    end
+
+    def update
+      permitted = role_params
+      previous_name = nil
+      saved = false
+      refused = false
+
+      # Lock full-access roles + holders inside the write transaction so two
+      # concurrent demotions of the last held full-access roles cannot both pass
+      # a pre-transaction check and then both commit.
+      Role.transaction do
+        # Lock FA console state before the target role so concurrent demote/delete
+        # of two FA roles cannot invert lock order (roles first, then assignments).
+        lock_full_access_console_state!
+        @role = Role.lock.find(params[:id])
+
+        if demoting_would_lock_console?(@role, permitted)
+          refused = true
+        else
+          previous_name = @role.name
+          previous_full_access = @role.full_access?
+          saved = @role.update(permitted)
+          record_role_update(@role, previous_name, previous_full_access) if saved
+        end
+      end
+
+      if refused
+        redirect_to edit_role_path(@role),
+                    alert: "Refusing to remove full access — this is the last full-access role " \
+                           "any subject holds and would lock everyone out of this UI. Grant " \
+                           "full access to another subject first, then retry."
+        return
+      end
+
+      if saved
+        redirect_to roles_path, notice: "Role updated."
+      else
+        render :edit, status: :unprocessable_entity
+      end
+    end
+
+    def destroy
+      refused = false
+
+      Role.transaction do
+        lock_full_access_console_state!
+        role = Role.lock.find(params[:id])
+
+        if would_lock_console_by_removing_role?(role)
+          refused = true
+        else
+          # Snapshot WITHOUT polymorphic includes — includes(:subject)/:resource
+          # can raise NameError for stale types at preload (members page avoids
+          # this for the same reason). Resolve each row inside the helpers.
+          org_removed = role.role_assignments.to_a
+          scoped_revoked = role.scoped_role_assignments.to_a
+
+          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: cascade_subject(a), details: { role: role.name })
+          end
+          scoped_revoked.each do |a|
+            Event.record!(event: "scoped_role.revoked", target: cascade_subject(a),
+                          details: { role: role.name, resource: cascade_resource_label(a) })
+          end
+        end
+      end
+
+      if refused
+        redirect_to roles_path,
+                    alert: "Refusing to delete this full-access role — it is the last one held by any " \
+                           "subject and would lock everyone out of this UI. Grant full access to " \
+                           "another subject first, then retry."
+        return
+      end
+
+      redirect_to roles_path, notice: "Role deleted."
+    end
+
+    private
+
+    # Polymorphic subject/resource may be deleted or unresolvable — never 500
+    # the cascade audit. Deleted records return nil without raising (especially
+    # after includes preload), so use || assignment, not rescue-only.
+    def cascade_subject(assignment)
+      assignment.current_scope_resolved_record("subject") || assignment
+    end
+
+    def cascade_resource_label(assignment)
+      resource = assignment.current_scope_resolved_record("resource")
+      return "#{assignment.resource_type}##{assignment.resource_id}" if resource.nil?
+
+      helpers.current_scope_label(resource)
+    rescue StandardError
+      "#{assignment.resource_type}##{assignment.resource_id}"
+    end
+
+    # One event per save: role.renamed when the name changed (carries old/new
+    # name AND the grid/full_access diff), else role.updated. Emits nothing on
+    # a pure no-op (same name, same grid, same full_access).
+    def record_role_update(role, previous_name, previous_full_access)
+      diff = role.permission_keys_change || { added: [], removed: [], rejected: [] }
+      renamed = previous_name != role.name
+      full_access_changed = previous_full_access != role.full_access?
+      return unless renamed || full_access_changed || diff[:added].any? || diff[:removed].any?
+
+      details = { added: diff[:added], removed: diff[:removed] }
+      if full_access_changed
+        details.merge!(full_access_from: previous_full_access, full_access_to: role.full_access?)
+      end
+      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
+
+    # True when removing/demoting this full_access role would leave zero
+    # full_access org holders. An unassigned full_access role is always safe
+    # to delete/demote (cubic). An empty spare full_access role must NOT
+    # authorize demoting the held Owner (CE) — check holders, not role rows.
+    def would_lock_console_by_removing_role?(role)
+      return false unless role.full_access?
+      return false unless RoleAssignment.where(role: role).exists?
+
+      !RoleAssignment.joins(:role)
+        .where(current_scope_roles: { full_access: true })
+        .where.not(role_id: role.id)
+        .exists?
+    end
+
+    # True when the update would turn off full_access and lock the console.
+    # Only treats an EXPLICIT full_access=false as demotion — a missing key
+    # would not change the column and must not false-positive refuse.
+    def demoting_would_lock_console?(role, permitted)
+      return false unless role.full_access?
+      return false unless permitted.key?(:full_access)
+      return false if ActiveModel::Type::Boolean.new.cast(permitted[:full_access])
+
+      would_lock_console_by_removing_role?(role)
+    end
+
+    # Serialize demote/delete against concurrent last-holder removal. Lock FA
+    # role rows and their org-wide holder assignments (by id — FOR UPDATE + join
+    # is adapter-fragile). Call only inside a transaction.
+    def lock_full_access_console_state!
+      Role.where(full_access: true).lock.load
+      ids = RoleAssignment.joins(:role)
+        .where(current_scope_roles: { full_access: true })
+        .pluck(:id)
+      RoleAssignment.where(id: ids).lock.load if ids.any?
+    end
+
+    # The candidate's primary key, rendered as text so it can be compared to the
+    # string subject_id column (#151). Adapters differ twice over: MySQL spells the
+    # cast CHAR where the others spell it TEXT, AND it refuses to compare two
+    # different collations.
+    #
+    # The collation is READ FROM THE COLUMN rather than hardcoded, so this cannot
+    # drift from what the migration set — and a host that chose a different binary
+    # collation still works.
+    def candidate_key_as_text
+      connection = subject_class.connection
+      column = "#{connection.quote_table_name(subject_class.table_name)}." \
+               "#{connection.quote_column_name(subject_class.primary_key)}"
+      return Arel.sql("CAST(#{column} AS TEXT)") unless CurrentScope.mysql?(connection)
+
+      collation = RoleAssignment.columns_hash["subject_id"]&.collation
+      raise ConfigurationError, "CurrentScope could not read subject_id's MySQL collation" if collation.blank?
+
+      cast = "CAST(#{column} AS CHAR)"
+      Arel.sql("#{cast} COLLATE #{collation}")
+    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 REJECTS anything not in the catalog (the
+      # save fails and `edit` re-renders with the error). The grid can't submit
+      # such a key — cells are built from routed actions only — so a rejection
+      # here means a hand-crafted request, which is worth saying out loud rather
+      # than dropping silently.
+      groups = params.fetch(:role, {}).permit(permission_groups: [])[:permission_groups]
+      permitted[:permission_keys] = Array(permitted[:permission_keys]) + PermissionGrid.new.expand(groups)
+      permitted
+    end
+  end
+end