current_scope 0.3.0 → 0.4.0

data/app/models/current_scope/event.rb

@@ -33,30 +33,45 @@ module CurrentScope
       #                               details: { name: "Owner" })
       #
       # Raises ConfigurationError (loud, matching the SoD posture) when there is
-      # no ambient actor. Silent no-op (returns nil) when config.audit is false.
-      def record!(event:, target:, details: nil)
+      # no ambient actor and no explicit actor: override. Silent no-op (returns
+      # nil) when config.audit is false.
+      #
+      # Optional actor:/subject: overrides (#30): when non-nil they replace the
+      # ambient reads so bootstrap paths (grant!, rake, seeds) can self-attribute
+      # without a controller. Omit both for byte-for-byte ambient behavior.
+      # Pin BOTH on a self-attributed grant so an ambient Current.user cannot
+      # leak into subject and mis-record the row as impersonation.
+      def record!(event:, target:, details: nil, actor: nil, subject: nil)
         return unless CurrentScope.config.audit
 
-        actor = CurrentScope::Current.actor
+        actor ||= CurrentScope::Current.actor
         if actor.nil?
           raise CurrentScope::ConfigurationError,
                 "CurrentScope::Event.record! has no actor — CurrentScope::Current.actor is nil. " \
                 "Set the ambient context (the controller hook, or with_current_user in tests) before recording."
         end
 
-        # Current.user is the effective subject; fall back to actor so subject
-        # is never nil (it equals actor whenever not impersonating).
-        subject = CurrentScope::Current.user || actor
+        # Explicit subject wins; else Current.user; else actor (never nil when
+        # actor is set, equals actor when not impersonating).
+        subject ||= CurrentScope::Current.user || actor
 
-        create!(
-          event: event.to_s,
-          actor: actor.to_gid.to_s,
-          subject: subject.to_gid.to_s,
-          target: target.to_gid.to_s,
-          target_label: label_for(target),
-          details: details,
-          request_id: CurrentScope::Current.request_id
-        )
+        # requires_new: on PostgreSQL a StatementInvalid aborts the *whole*
+        # open transaction even if rescued — so a missing events table would
+        # poison grant!/controller mutation transactions that wrap record!.
+        # A savepoint isolates the audit write: default audit=true degrades
+        # and the assignment commits; :strict re-raises and rolls the outer
+        # mutation back (PR #102 review).
+        Event.transaction(requires_new: true) do
+          create!(
+            event: event.to_s,
+            actor: actor.to_gid.to_s,
+            subject: subject.to_gid.to_s,
+            target: target.to_gid.to_s,
+            target_label: label_for(target),
+            details: details,
+            request_id: CurrentScope::Current.request_id
+          )
+        end
       rescue ActiveRecord::StatementInvalid => e
         raise unless missing_events_table?(e)
 

data/app/models/current_scope/scoped_role_assignment.rb

@@ -2,6 +2,10 @@ module CurrentScope
   # A role held on ONE specific record: "Editor of Project #7" grants nothing
   # on Project #8. Never touches the subject's org-wide role — the two are
   # independent axes.
+  #
+  # Rows survive host resource destruction by design (polymorphic, no
+  # dependent:). Since #65 those orphan grants open nothing (empty list = 403)
+  # but still rendered like live access until labeled (#90).
   class ScopedRoleAssignment < ApplicationRecord
     belongs_to :role
     belongs_to :subject, polymorphic: true
@@ -10,5 +14,52 @@ module CurrentScope
     validates :role_id, uniqueness: {
       scope: [ :subject_type, :subject_id, :resource_type, :resource_id ]
     }
+
+    # Batch-load polymorphic resources for resolvable types only. A global
+    # includes(:resource) NameErrors when any resource_type is stale; this
+    # constantizes per type and skips unresolvable ones so they stay lazy
+    # and orphaned_resource? labels them inert (#90 / PR #104 review).
+    def self.preload_resolvable_resources!(assignments)
+      list = Array(assignments)
+      return list if list.empty?
+
+      list.group_by(&:resource_type).each do |type, rows|
+        next if type.blank?
+
+        klass =
+          begin
+            type.constantize
+          rescue NameError
+            next
+          end
+        next unless klass.respond_to?(:where)
+
+        records = klass.where(id: rows.map(&:resource_id).uniq).index_by { |r| r.id }
+        rows.each do |row|
+          assoc = row.association(:resource)
+          assoc.target = records[row.resource_id]
+          assoc.loaded!
+        end
+      end
+
+      list
+    end
+
+    # True when the pointed-at resource is gone (deleted row or unresolvable
+    # type). The grant is inert for authorization (#65) but still a console row.
+    # Memoized: views call this plus the label helper once each; a reset-every-
+    # call would re-query the resource twice per row (PR #104 cubic follow-up).
+    def orphaned_resource?
+      return @orphaned_resource if defined?(@orphaned_resource)
+
+      @orphaned_resource =
+        if resource_id.blank?
+          false
+        else
+          resource.nil?
+        end
+    rescue NameError, ActiveRecord::RecordNotFound
+      @orphaned_resource = true
+    end
   end
 end

data/app/views/current_scope/roles/index.html.erb

@@ -30,9 +30,23 @@
         </td>
         <td>
           <%= link_to "Members", members_role_path(role), class: "cs-btn" %>
+          <%
+            org_n = role.role_assignments.size
+            scoped_n = role.scoped_role_assignments.size
+            parts = []
+            parts << "#{org_n} org-wide #{"holder".pluralize(org_n)}" if org_n.positive?
+            parts << "#{scoped_n} scoped #{"holder".pluralize(scoped_n)}" if scoped_n.positive?
+            delete_prompt = if parts.empty?
+              "Delete role #{role.name}?"
+            else
+              "Delete role #{role.name}? This also removes it from #{parts.to_sentence}."
+            end
+          %>
           <%= button_to "Delete", role_path(role), method: :delete,
-                form: { data: { cs_confirm: "Delete role #{role.name}?" } },
-                data: { turbo_confirm: "Delete role #{role.name}?" } %>
+                class: "cs-btn cs-btn-danger",
+                form: { data: { cs_confirm: delete_prompt } },
+                aria: { label: "Delete role #{role.name}" },
+                data: { turbo_confirm: delete_prompt } %>
         </td>
       </tr>
     <% end %>

data/app/views/current_scope/roles/members.html.erb

@@ -77,12 +77,24 @@
         <% @scoped_holders.each do |sra| %>
           <% who = current_scope_holder_subject_label(sra) %>
           <% what = current_scope_holder_resource_label(sra) %>
-          <tr>
+          <% orphaned = sra.orphaned_resource? %>
+          <tr id="scoped_holder_<%= sra.id %>"
+              class="cs-scoped-holder<%= ' cs-row--inert' if orphaned %>">
             <td><%= who %></td>
-            <td><%= what %></td>
             <td>
-              <% revoke_prompt = "Revoke #{@role.name} on #{what} from #{who}?" %>
-              <%= button_to "Revoke", scoped_role_assignment_path(sra), method: :delete,
+              <%= what %>
+              <% if orphaned %>
+                <span class="cs-inert-badge"
+                      title="This resource no longer resolves; the grant opens nothing on collection reads">inert</span>
+              <% end %>
+            </td>
+            <td>
+              <% revoke_prompt = orphaned ?
+                    "Remove inert scoped grant (resource unavailable) for #{who}?" :
+                    "Revoke #{@role.name} on #{what} from #{who}?" %>
+              <%= button_to (orphaned ? "Remove inert" : "Revoke"),
+                    scoped_role_assignment_path(sra), method: :delete,
+                    id: "scoped_revoke_#{sra.id}",
                     class: "cs-btn", form: { data: { cs_confirm: revoke_prompt } },
                     data: { turbo_confirm: revoke_prompt } %>
             </td>

data/app/views/current_scope/scoped_role_assignments/new.html.erb

@@ -24,15 +24,15 @@
 <%= form_with url: new_scoped_role_assignment_path, method: :get, id: "cs-cascade",
       data: { turbo_frame: "cascade" }, class: "cs-picker" do %>
   <p>
-    <label>Role</label>
+    <%= label_tag :role_id, "Role" %>
     <%= select_tag :role_id,
           options_from_collection_for_select(@roles, :id, :name, params[:role_id]),
           data: { current_scope_autosubmit: true } %>
   </p>
   <% if @bulk_subjects.any? %>
     <p>
-      <label>Subjects</label>
-      <span class="cs-hint">
+      <span class="cs-label" id="cs_bulk_subjects_label">Subjects</span>
+      <span class="cs-hint" aria-labelledby="cs_bulk_subjects_label">
         Granting to <strong><%= @bulk_subjects.size %></strong>:
         <%= @bulk_subjects.map { |s| current_scope_subject_label(s) }.to_sentence %>
       </span>
@@ -42,7 +42,7 @@
     </p>
   <% else %>
     <p>
-      <label>Subject</label>
+      <%= label_tag :subject_gid, "Subject" %>
       <%= select_tag :subject_gid,
             options_for_select(@subjects.map { |s| [ current_scope_subject_label(s), s.to_gid.to_s ] },
                                params[:subject_gid]),
@@ -67,7 +67,7 @@
       end
     %>
     <p>
-      <label>Resource type</label>
+      <%= label_tag :resource_type, "Resource type" %>
       <%= select_tag :resource_type,
             options_for_select(type_options, @resource_type&.name),
             include_blank: "— choose a type —", form: "cs-cascade",
@@ -82,13 +82,13 @@
       <% else %>
         <% if @searchable %>
           <p>
-            <label>Search records</label>
+            <%= label_tag :q, "Search records" %>
             <%= search_field_tag :q, params[:q], placeholder: "Filter by label",
                   form: "cs-cascade", data: { current_scope_autosubmit: true } %>
           </p>
         <% end %>
         <p>
-          <label>Record</label>
+          <%= label_tag :resource_gid, "Record" %>
           <%
             record_options = (@records || []).map { |record| [ current_scope_label(record), record.to_gid.to_s ] }
             # Keep a deep-linked record selectable even if it fell outside the

data/app/views/current_scope/subjects/index.html.erb

@@ -63,7 +63,9 @@
           <select> listing all role names, which would match every query. %>
       <% org_role_name = @roles.find { |r| r.id == @assignments[key]&.role_id }&.name %>
       <% filter_text = [ label, org_role_name,
-                         *(@scoped[key] || []).map { |sra| "#{sra.role.name} #{current_scope_label(sra.resource)}" } ].compact.join(" ") %>
+                         *(@scoped[key] || []).map { |sra|
+                           "#{sra.role.name} #{current_scope_holder_resource_label(sra)}"
+                         } ].compact.join(" ") %>
       <tr data-cs-row data-cs-filter-text="<%= filter_text %>">
         <td class="cs-select-cell">
           <input type="checkbox" data-cs-select value="<%= subject.to_gid %>"
@@ -77,20 +79,30 @@
             <%= hidden_field_tag :subject_gid, subject.to_gid %>
             <%= select_tag :role_id,
                   options_from_collection_for_select(@roles, :id, :name, @assignments[key]&.role_id),
-                  include_blank: "— none —" %>
-            <%= submit_tag "Set", name: nil %>
+                  include_blank: "— none —",
+                  aria: { label: "Org-wide role for #{label}" } %>
+            <%= submit_tag "Set", name: nil,
+                  aria: { label: "Set org-wide role for #{label}" } %>
           <% end %>
         </td>
         <td>
           <% (@scoped[key] || []).each do |sra| %>
-            <span class="cs-chip">
-              <span class="cs-chip-label"><%= sra.role.name %> of <%= current_scope_label(sra.resource) %></span>
-              <% revoke_prompt = "Revoke #{sra.role.name} on #{current_scope_label(sra.resource)}?" %>
+            <% resource_label = current_scope_holder_resource_label(sra) %>
+            <% orphaned = sra.orphaned_resource? %>
+            <span class="cs-chip cs-scoped-chip<%= ' cs-chip--inert' if orphaned %>" id="scoped_chip_<%= sra.id %>">
+              <span class="cs-chip-label">
+                <%= sra.role.name %> of <%= resource_label %>
+                <% if orphaned %><span class="cs-inert-badge">inert</span><% end %>
+              </span>
+              <% revoke_prompt = orphaned ?
+                    "Remove inert scoped grant (#{resource_label})?" :
+                    "Revoke #{sra.role.name} on #{resource_label}?" %>
               <%= button_to "×", scoped_role_assignment_path(sra), method: :delete,
                     class: "cs-chip-remove",
-                    title: "Revoke this scoped role",
+                    id: "scoped_chip_revoke_#{sra.id}",
+                    title: (orphaned ? "Remove inert scoped grant" : "Revoke this scoped role"),
                     form: { data: { cs_confirm: revoke_prompt } },
-                    aria: { label: "Revoke #{sra.role.name} on #{current_scope_label(sra.resource)}" },
+                    aria: { label: (orphaned ? "Remove inert #{sra.role.name} grant on #{resource_label}" : "Revoke #{sra.role.name} on #{resource_label}") },
                     data: { turbo_confirm: revoke_prompt } %>
             </span>
           <% end %>

data/lib/current_scope/configuration.rb

@@ -17,7 +17,11 @@ module CurrentScope
     # EMPTY BY DEFAULT — SoD is opt-in. The engine's baseline is scoped RBAC;
     # many hosts want nothing to do with four-eyes. Enable it by listing the
     # actions to gate, e.g. `config.sod_actions = %w[approve]`.
-    attr_accessor :sod_actions
+    #
+    # Matched as STRINGS against the key's action segment (see Resolver#sod_action?).
+    # Use the writer below — a plain Symbol list ([:approve]) used to silently
+    # disable the veto (#91). Same shape as collection_read_actions=.
+    attr_reader :sod_actions
 
     # Which identities the separation-of-duties veto weighs:
     #   :either  (default) — veto if the effective subject OR (while
@@ -32,6 +36,32 @@ module CurrentScope
 
     SOD_IDENTITY_MODES = %i[either subject].freeze
 
+    # Normalizing writer for sod_actions (#91). The resolver matches with
+    # include?(permission.split("#").last) — a String — so symbols never match
+    # and silently turn the fraud control off. Normalize symbols to strings,
+    # reject non-String/Symbol elements and full keys (same honesty as
+    # collection_read_actions=), freeze the list.
+    def sod_actions=(value)
+      elements = Array(value)
+
+      if (bad = elements.reject { |e| e.is_a?(String) || e.is_a?(Symbol) }).any?
+        raise ConfigurationError,
+              "config.sod_actions takes action NAMES (strings or symbols); got " \
+              "#{bad.map(&:inspect).join(', ')}. Write e.g. %w[approve] or [:approve]."
+      end
+
+      actions = elements.map(&:to_s)
+
+      if (keyed = actions.grep(/#/)).any?
+        raise ConfigurationError,
+              "config.sod_actions is matched on the ACTION segment of a key — " \
+              "#{keyed.map(&:inspect).join(', ')} can never match. Write \"approve\", " \
+              "not \"reports#approve\"."
+      end
+
+      @sod_actions = actions.freeze
+    end
+
     # Validating writer, same contract as enforcement=: the resolver compares
     # `== :either`, so a typo (`:both`, `:actor`) would otherwise silently
     # behave as :subject — narrowing the fraud control with no signal. Raise at
@@ -76,6 +106,8 @@ module CurrentScope
     # controllers out of the permission grid. An excluded controller cannot be
     # granted, so it must also skip the gate
     # (skip_before_action :current_scope_check!) — Guard raises otherwise.
+    # Skipping the gate leaves the controller ungated by CurrentScope — protect
+    # it with your own authorization (e.g. require_admin!). See docs/SECURITY-CHECKLIST.md.
     attr_accessor :excluded_controllers
 
     # Class the management UI's controllers inherit from, so they pick up the
@@ -161,12 +193,11 @@ module CurrentScope
     # reads, so review the declaration like the record hook.
     attr_reader :collection_read_actions
 
-    # Normalizing writer, unlike sod_actions' plain accessor (that footgun is
-    # grandfathered, not precedent): the list is matched as STRINGS, so
-    # [:index] matching nothing would silently un-fix #65. Normalize rather
-    # than raise for shape (nil ⇒ [], symbols ⇒ strings — unambiguous), but
-    # two inputs get a voice, because a silently-inert or silently-widened
-    # security knob is the failure this writer exists to prevent:
+    # Normalizing writer: the list is matched as STRINGS, so [:index] matching
+    # nothing would silently un-fix #65. Normalize rather than raise for shape
+    # (nil ⇒ [], symbols ⇒ strings — unambiguous), but two inputs get a voice,
+    # because a silently-inert or silently-widened security knob is the failure
+    # this writer exists to prevent:
     #
     #   - a full KEY ("reports#index") RAISES — the list is matched on the
     #     action segment and applies to every controller, so a keyed member
@@ -213,9 +244,11 @@ module CurrentScope
       @collection_read_actions = actions.freeze
     end
 
-    # The three canonical Rails write actions — the unambiguous slice of the
-    # mutating-action space the writer above warns about.
-    MUTATING_ACTION_NAMES = %w[create update destroy].freeze
+    # Canonical mutating / bulk-write action names the collection_read writer
+    # warns about. Includes destroy_all/update_all — the docs' escalation
+    # examples — so those cannot reintroduce #49 via config with no signal.
+    # Custom names still evade any partial blocklist; that ceiling is deliberate.
+    MUTATING_ACTION_NAMES = %w[create update destroy destroy_all update_all].freeze
 
     # Tri-state: false | true (default) | :strict — controls
     # CurrentScope::Event.record!.
@@ -407,7 +440,7 @@ module CurrentScope
     def initialize
       @user_method = :current_user
       @actor_method = nil
-      @sod_actions = []
+      @sod_actions = [].freeze
       @sod_identity = :either
       @allow_sod_bypass = false
       @sod_bypass_permission = "bypass_sod"
@@ -461,6 +494,43 @@ module CurrentScope
       @allow_mutations_while_impersonating = value
     end
 
+    # Action segment of sod_bypass_permission — bare name or "controller#action".
+    # Shared by boot validation and the resolver's recursion guard so the two
+    # never normalize differently (#40). Uses split("#", -1) like
+    # PermissionCatalog#bypass_action: plain split("#").last turns "reports#"
+    # into "reports" (trailing empty dropped) and multi-hash values into the
+    # wrong last segment — false conflicts or missed recursion guards.
+    # Malformed shapes return nil (no false conflict); the catalog still raises
+    # loudly when allow_sod_bypass is on and the key is malformed.
+    def sod_bypass_action
+      segments = sod_bypass_permission.to_s.split("#", -1)
+      return if segments.empty? || segments.size > 2 || segments.any?(&:blank?)
+
+      segments.last
+    end
+
+    # True when the break-glass bypass permission is also listed in sod_actions.
+    # That pairing would re-enter the SoD step on every bypass check and stack
+    # overflow. Never valid in any environment (#40).
+    def sod_bypass_permission_conflicts_with_sod_actions?
+      action = sod_bypass_action
+      action.present? && sod_actions.include?(action)
+    end
+
+    # Boot-time config invariants. Wired from Engine#after_initialize after the
+    # host initializer has finalized both fields. Extensible seam for future
+    # multi-field checks; today only the bypass-in-sod_actions recursion rule.
+    def validate!
+      return unless sod_bypass_permission_conflicts_with_sod_actions?
+
+      action = sod_bypass_action
+      raise ConfigurationError,
+            "config.sod_bypass_permission (#{sod_bypass_permission.inspect}) is the " \
+            "action #{action.inspect}, which is also in config.sod_actions. The bypass " \
+            "permission must not be an SoD action — it would recurse. Remove " \
+            "#{action.inspect} from sod_actions."
+    end
+
     private
 
     # The env var's VALUE means what it says — presence alone is not consent.

data/lib/current_scope/context.rb

@@ -23,6 +23,11 @@ module CurrentScope
       # falls back to the subject. Only resolve when the host opts in.
       actor_method = CurrentScope.config.actor_method
       CurrentScope::Current.actor = resolve_current_scope_subject(actor_method) if actor_method
+
+      # Correlation for the audit ledger (#30). ActionDispatch::RequestId runs
+      # ahead of app before_actions; job/console contexts never enter this hook
+      # and leave request_id nil by design.
+      CurrentScope::Current.request_id = request.request_id
     end
 
     def resolve_current_scope_subject(method)

data/lib/current_scope/engine.rb

@@ -2,6 +2,35 @@ module CurrentScope
   class Engine < ::Rails::Engine
     isolate_namespace CurrentScope
 
+    # An AccessDenied that escapes any Guard rescue (PORO, Context-only
+    # controller, re-raise) must 403, not 500. Never turns a deny into an
+    # allow — the exception already blocked the action (#39).
+    #
+    # ||= so a host that already set this mapping (e.g. :not_found to hide
+    # existence) in config/application.rb is not clobbered. before:
+    # action_dispatch.configure so ExceptionWrapper.rescue_responses picks the
+    # entry up when it merge!s the config hash.
+    initializer "current_scope.rescue_responses", before: "action_dispatch.configure" do |app|
+      app.config.action_dispatch.rescue_responses["CurrentScope::AccessDenied"] ||= :forbidden
+    end
+
+    # Belt for Rails upgrades: if action_dispatch.configure is renamed/reordered
+    # and the config merge is missed, still pin the class map. Use key? — the
+    # ExceptionWrapper hash defaults missing keys to :internal_server_error
+    # (truthy), so ||= would never write.
+    initializer "current_scope.rescue_responses_apply", after: "action_dispatch.configure" do
+      map = ActionDispatch::ExceptionWrapper.rescue_responses
+      map["CurrentScope::AccessDenied"] = :forbidden unless map.key?("CurrentScope::AccessDenied")
+    end
+
+    # Cross-field config invariants (e.g. bypass permission ∉ sod_actions) must
+    # run AFTER the host initializer has assigned every field — a writer on
+    # either attr alone is order-dependent. once, not on to_prepare (config
+    # does not change on code reload). #40.
+    config.after_initialize do
+      CurrentScope.config.validate!
+    end
+
     # Routes (and therefore the derived permission catalog) can change on
     # every code reload in development, and reloaded host models must re-register
     # as scopeable rather than pile up stale/duplicate entries. Both reset here,