current_scope 0.2.0 → 0.3.0

data/lib/current_scope/permission_catalog.rb

@@ -1,3 +1,8 @@
+# Enumerable#to_set (key_set, the routed-key cache) is stdlib `set`, which a
+# full Rails boot happens to load — a host on active_support.bare would
+# NoMethodError at catalog construction without the explicit require.
+require "set"
+
 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
@@ -13,21 +18,129 @@ module CurrentScope
           .transform_values { |ks| ks.map { |k| k.split("#").last } }
     end
 
+    # Hot: the Guard asks this on EVERY gated request, and a role save asks it
+    # once per staged key. Set lookup, not Array#include? — the array is sorted
+    # for display, and scanning it linearly made every request pay for the size
+    # of the host's route table. Memoized alongside `keys` and dropped with it
+    # on reset!.
     def include?(key)
-      keys.include?(key)
+      key_set.include?(key)
+    end
+
+    # The ONE parse of config.sod_bypass_permission's action segment — the grid
+    # view and the ungated task read it here rather than re-splitting the
+    # string themselves (a looser split("#").last silently turns a malformed
+    # "reports#" into "reports" and mislabels the break-glass cell; #79 review).
+    #
+    # `split("#", -1)` keeps the trailing empty field, so a malformed "reports#"
+    # yields "" and is caught here rather than silently becoming "reports" and
+    # injecting "reports#reports". Blank raises instead of skipping: the host
+    # turned break-glass ON, so a permission nobody can hold means the veto can
+    # never be lifted and the feature is inert — an undiagnosable deny, which is
+    # exactly what this engine promises not to do. (A boot-time check for this
+    # config belongs with #40.)
+    def bypass_action
+      segments = CurrentScope.config.sod_bypass_permission.to_s.split("#", -1)
+      # Exactly a bare action or one controller#action. More hashes would pass
+      # a last-segment check while the resolver reads the ORIGINAL full string —
+      # the catalog would inject a key nobody can be granted under, and the
+      # veto could never be lifted. (#79 review)
+      if segments.empty? || segments.size > 2 || segments.any?(&:blank?)
+        raise ConfigurationError,
+              "config.allow_sod_bypass is on, but config.sod_bypass_permission " \
+              "(#{CurrentScope.config.sod_bypass_permission.inspect}) is not a bare action or a " \
+              "single controller#action. Name the permission the record's initiator must hold " \
+              "to break glass (the default is \"bypass_sod\"), or set config.allow_sod_bypass = false."
+      end
+
+      segments.last
+    end
+
+    # Is this key derived from a real route (as opposed to the injected
+    # break-glass key)? The distinction matters to anything making an
+    # inertness claim: a ROUTED action named like the bypass permission is an
+    # ordinary action and gets no exemption, while the injected key is live on
+    # any row. (#79 review)
+    def routed?(key)
+      keys # derive memoizes @routed_key_set as a side effect
+      @routed_key_set.include?(key)
     end
 
     private
 
+    def key_set
+      @key_set ||= keys.to_set
+    end
+
     def derive
-      Rails.application.routes.routes.filter_map { |route|
+      routed = 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
+      }.uniq
+
+      @routed_key_set = routed.to_set
+      (routed + bypass_keys(routed)).uniq.sort
     end
+
+    # Break-glass is the one permission that isn't an action you can route: it
+    # gates the SoD veto rather than a request. So a purely route-derived catalog
+    # can never contain it — which left the shipped "grantable, editable in the
+    # role grid" claim false, and break-glass reachable only through full_access
+    # (defeating the point of a *scoped* trusted-approver role) or a console
+    # insert. The catalog is the single definition of what is grantable — the
+    # grid reads `grouped`, the role setter and the Guard read `include?` — so
+    # injecting the virtual key here makes the cell render AND the save stick,
+    # with no special case in either. (#21)
+    #
+    # Emitted only where it could mean something: break-glass on, and a
+    # controller that actually routes an SoD action. Off by default, so the
+    # catalog is byte-for-byte the routed set unless a host opts in.
+    #
+    # Route- and config-derived only — deliberately no model introspection. The
+    # precise set would be "controllers whose SoD-gated model defines an
+    # initiator", but discovering that means loading application models, which
+    # is expensive, boot-order fragile, and against the catalog's whole design.
+    #
+    # The key is built from the controller's LAST path segment, because that is
+    # what the resolver will ask for: it derives the bypass key from the
+    # RECORD's route_key (permission_key → record.model_name.route_key), never
+    # from the controller path. Under Rails' resource conventions those agree —
+    # Admin::ReportsController's last segment "reports" IS Report's route_key —
+    # so keying off the whole path would inject "admin/reports#bypass_sod" while
+    # the resolver looks up "reports#bypass_sod", leaving break-glass ungrantable
+    # for every namespaced SoD controller and handing the admin a cell that
+    # silently does nothing. Namespaced admin controllers are common enough that
+    # this is the difference between the fix working and not.
+    #
+    # A namespace-only resource therefore gets its bypass cell on a "reports"
+    # row that no controller routes — the grid renders it aligned, blank
+    # everywhere else. Slightly odd to look at, and correct: it is the key the
+    # resolver actually reads.
+    #
+    # The irreducible limit: a controller named differently from the records it
+    # acts on (an `approvals` controller approving `Invoice`s) still injects
+    # `approvals#bypass_sod` while the live key is `invoices#bypass_sod`.
+    # Closing that needs to know the SoD-gated model, i.e. introspection.
+    # Tracked at OQ-2.
+    def bypass_keys(routed)
+      return [] unless CurrentScope.config.allow_sod_bypass
+
+      sod_actions = CurrentScope.config.sod_actions
+      return [] if sod_actions.empty?
+
+      routed.group_by { |key| key.split("#").first }
+            .filter_map { |controller, keys|
+              actions = keys.map { |k| k.split("#").last }
+              "#{controller.split('/').last}##{bypass_action}" if actions.intersect?(sod_actions)
+            }
+    end
+
+    # The action segment of config.sod_bypass_permission — tolerating either a
+    # bare action ("bypass_sod") or a full key ("reports#bypass_sod").
+    #
   end
 end

data/lib/current_scope/permission_grid.rb

@@ -1,3 +1,7 @@
+# The gating: default below constructs one at call time — a caller requiring
+# this file directly (not via the current_scope entrypoint) must not NameError.
+require "current_scope/gating_reflection"
+
 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
@@ -13,15 +17,31 @@ module CurrentScope
     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)
+    # The gating default is evaluated at CALL time, so every bare
+    # PermissionGrid.new (the edit view AND role_params on every role save)
+    # constructs a GatingReflection. That is fine only because its constructor
+    # is inert by contract — all reflection work happens inside #ungated?, and
+    # nothing here calls it during initialize or #expand (KTD-8; pinned by the
+    # spy test).
+    def initialize(catalog: CurrentScope.catalog, groups: CurrentScope.config.permission_grid_groups,
+                   gating: GatingReflection.new)
       @grouped = catalog.grouped # { "controller" => ["action", ...] }
       @groups  = groups || {}
+      @gating  = gating
     end
 
     def controllers
       @grouped.keys.sort
     end
 
+    # Is this row's controller provably never gated? Advisory only — a pure
+    # delegation the view reads to annotate the row; no other grid method
+    # consults the reflection, so the answer cannot affect a cell or an
+    # expansion (pinned byte-identical in the tests).
+    def ungated?(controller)
+      @gating.ungated?(controller)
+    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
@@ -61,14 +81,24 @@ module CurrentScope
     end
 
     # Expand submitted "controller:group" tokens into routed permission keys.
-    # Unknown groups/controllers and unrouted actions drop out.
+    #
+    # A token the grid could not have produced (unknown group, unknown
+    # controller, nothing routed) passes through RAW so the model's catalog
+    # validation rejects it BY NAME — the same loud contract a hand-crafted
+    # permission_keys[] entry gets. One save, one error story: the grid's two
+    # submission channels must not differ on whether a crafted request is
+    # reported or silently swallowed. (The form's blank hidden padding is the
+    # one legitimate non-grid value; it alone drops out.)
     def expand(tokens)
       Array(tokens).flat_map do |token|
+        next [] if token.blank?
+
         controller, label = token.to_s.split(":", 2)
         actions = @groups[label]
-        next [] if actions.nil?
+        routed = actions ? (actions & actions_for(controller)) : []
+        next [ token.to_s ] if routed.empty?
 
-        (actions & actions_for(controller)).map { |action| "#{controller}##{action}" }
+        routed.map { |action| "#{controller}##{action}" }
       end
     end
 

data/lib/current_scope/permissions.rb

@@ -13,14 +13,28 @@ module CurrentScope
     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)
+        controller_path: controller, actor: current_scope_actor,
+        model: ambient_collection_model(action, controller))
     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.
+    # effective subject act on?". Same grants and keys as the gate, resolved
+    # fail-closed (nil subject / no grant → none) — but scope_for answers ROW
+    # MEMBERSHIP only, never action reachability. Gate checks that sit on top
+    # of the grant do not filter this list:
+    #   - the separation-of-duties veto — for an SoD-listed action the list CAN
+    #     include the subject's own initiated records, which the per-record
+    #     gate then refuses;
+    #   - the impersonation mutation gate — a REQUEST-level guard, not a
+    #     per-record one: it blocks any non-GET/HEAD request while
+    #     impersonating, collection actions included;
+    #   - record-less gate paths (a hookless controller's NO_RECORD decision).
+    # So a listed row can still 403 when acted on. Per-row affordances for
+    # SoD-listed actions must check allowed_to?(action, record); mutation
+    # affordances while impersonating should key off impersonating?.
+    # 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)
@@ -37,6 +51,26 @@ module CurrentScope
       )
     end
 
+    # The type the controller handling THIS request declared for its collection
+    # actions (#50), so a bare allowed_to?(:index) in its own view binds the
+    # record-less gate the same way the gate did — otherwise the fix would hide
+    # a link the gate allows. Only for the request's OWN controller: a
+    # cross-controller question resolves a key about a different controller than
+    # the ambient type answers, so it gets nil and falls to the fail-closed
+    # default — the class form allowed_to?(:index, Report) is how you ask about
+    # another controller, and it binds from its argument (R5). (KTD-6)
+    #
+    # The match keys on the KEY's controller, not just the controller: kwarg: a
+    # full "reports#index" key from a projects view names "reports" and must NOT
+    # borrow the projects ambient (a Project grant answering a reports key). A
+    # bare action uses the resolved controller. (#50 review, cubic)
+    def ambient_collection_model(action, controller)
+      key_controller = action.to_s.include?("#") ? action.to_s.split("#").first : controller
+      return nil unless key_controller && key_controller == CurrentScope::Current.collection_model_path
+
+      CurrentScope::Current.collection_model
+    end
+
     def current_scope_user
       CurrentScope::Current.user
     end
@@ -48,10 +82,10 @@ module CurrentScope
     end
 
     # True only while a distinct real actor stands behind the effective
-    # subject (act-as). Views use it as the read-only-state signal.
+    # subject (act-as). Views use it as the read-only-state signal. Delegates
+    # to the one definition on Current, shared with the mutation guard.
     def impersonating?
-      CurrentScope::Current.user.present? &&
-        CurrentScope::Current.actor != CurrentScope::Current.user
+      CurrentScope::Current.impersonating?
     end
   end
 end