current_scope 0.5.0

data/lib/current_scope/permission_grid.rb

@@ -0,0 +1,132 @@
+# 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
+  # controller doesn't route a column's actions (never a shifted cell).
+  #
+  # By default the columns are CRUD groups (config.permission_grid_groups):
+  # ticking one grants every routed action in the group, so the RESTful form
+  # actions fold into their mutation (new→create, edit→update) and index+show
+  # read as one. Actions outside any group (e.g. "approve") get their own
+  # column. With groups set to nil/{} every raw action becomes its own column —
+  # still aligned.
+  class PermissionGrid
+    Column = Struct.new(:label, :actions, :group, keyword_init: true)
+    Cell   = Struct.new(:blank, :group, :name, :value, :checked, :partial, :granted_keys, keyword_init: true)
+
+    # 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
+
+    # Is this row's controller class missing (stale/typo route)? Advisory only
+    # — badge the row; do not drop the catalog key (the catalog is a route
+    # mirror). (#43)
+    def missing_controller?(controller)
+      @gating.missing_controller?(controller)
+    end
+
+    # Declared skip reason from current_scope_skip_gate!, or nil (#76).
+    def declared_skip_reason(controller)
+      @gating.declared_skip_reason(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
+      grouped = @groups.filter_map do |label, actions|
+        Column.new(label: label, actions: actions, group: true) if any_controller_has?(actions)
+      end
+      grouped + leftover_actions.map { |action| Column.new(label: action, actions: [ action ], group: false) }
+    end
+
+    # One cell for (controller, column) against a role's granted key set.
+    # Blank when the controller routes none of the column's actions. Otherwise a
+    # checkbox.
+    #
+    # A GROUP cell is only `checked` when EVERY routed action is granted — a
+    # partial group is rendered unchecked+indeterminate and its existing keys are
+    # preserved verbatim via hidden inputs (see the edit view). This is the
+    # escalation guard: a checked group token expands to the whole group on save,
+    # so treating "some granted" as checked would silently promote a partial
+    # grant to a full one just by re-saving the role. `granted_keys` carries the
+    # exact subset to round-trip for a partial cell.
+    def cell(controller, column, granted)
+      routed = column.actions & actions_for(controller)
+      return Cell.new(blank: true) if routed.empty?
+
+      keys = routed.map { |action| "#{controller}##{action}" }
+      present_keys = keys.select { |key| granted.include?(key) }
+      partial = present_keys.any? && present_keys.size < keys.size
+      Cell.new(
+        blank: false,
+        group: column.group,
+        name:  column.group ? "role[permission_groups][]" : "role[permission_keys][]",
+        value: column.group ? "#{controller}:#{column.label}" : keys.first,
+        checked: column.group ? (present_keys.any? && !partial) : present_keys.any?,
+        partial: partial,
+        granted_keys: partial ? present_keys : []
+      )
+    end
+
+    # Expand submitted "controller:group" tokens into routed permission keys.
+    #
+    # 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]
+        routed = actions ? (actions & actions_for(controller)) : []
+        next [ token.to_s ] if routed.empty?
+
+        routed.map { |action| "#{controller}##{action}" }
+      end
+    end
+
+    def actions_for(controller)
+      @grouped[controller] || []
+    end
+
+    private
+
+    def any_controller_has?(actions)
+      @grouped.values.any? { |routed| routed.intersect?(actions) }
+    end
+
+    def leftover_actions
+      grouped = @groups.values.flatten.uniq
+      (@grouped.values.flatten.uniq - grouped).sort
+    end
+  end
+end

data/lib/current_scope/permissions.rb

@@ -0,0 +1,94 @@
+module CurrentScope
+  # The portable authorization mixin. Works anywhere — controllers, views,
+  # components, POROs — because the subject comes from the ambient
+  # CurrentScope::Current context rather than being threaded through calls.
+  # Everything delegates to the one resolver, so a view can never disagree
+  # with the controller gate.
+  #
+  #   allowed_to?(:approve, report)          # key derived from the record
+  #   allowed_to?(:create, Report)           # class works for collection actions
+  #   allowed_to?("admin/reports#approve")   # explicit full key
+  #   allowed_to?(:index, controller: "reports")
+  module Permissions
+    def allowed_to?(action, record = nil, controller: nil)
+      controller ||= controller_path if respond_to?(:controller_path)
+      CurrentScope.allowed?(action, subject: current_scope_user, record: record,
+        controller_path: controller, actor: current_scope_actor,
+        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 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)
+    #   scope_for(Report, permission: "admin/reports#approve")
+    def scope_for(model, permission: nil)
+      # Derive the key exactly like allowed_to? — including controller_path, so a
+      # namespaced controller's list resolves to the same key as its gate
+      # (admin/reports#index, not reports#index) and the two never drift.
+      controller = controller_path if respond_to?(:controller_path)
+      CurrentScope.scope_for(
+        subject: current_scope_user,
+        model: model,
+        permission: CurrentScope.permission_key(permission || :index, record: model, controller_path: controller)
+      )
+    end
+
+    # 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)
+    #
+    def current_scope_user
+      CurrentScope::Current.user
+    end
+
+    # The REAL actor behind the request (never nil when a subject is set — it
+    # falls back to the subject). Read this for attribution, not Current.
+    def current_scope_actor
+      CurrentScope::Current.actor
+    end
+
+    # True only while a distinct real actor stands behind the effective
+    # subject (act-as). Views use it as the read-only-state signal. Delegates
+    # to the one definition on Current, shared with the mutation guard.
+    def impersonating?
+      CurrentScope::Current.impersonating?
+    end
+
+    private
+
+    # Internal binding for gate/view agreement (#50 KTD-6) — not host API.
+    # Private so it does not appear in controller action_methods. Matches on
+    # the KEY's controller, not just the controller: kwarg: a full
+    # "reports#index" key from a projects view must not borrow the projects
+    # ambient. 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
+  end
+end