current_scope 0.2.0

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

@@ -0,0 +1,100 @@
+<h1>Subjects</h1>
+<p class="cs-lede">Everyone who can hold a role, with their one org-wide role and
+  any per-record scoped roles. Filter to find people; select several to grant a
+  scoped role in one go.</p>
+
+<div class="cs-toolbar">
+  <%= form_with url: subjects_path, method: :get, class: "cs-search", role: "search" do %>
+    <input type="search" name="q" value="<%= @query %>" class="cs-filter" data-cs-filter
+           placeholder="Search everyone by email or name…" aria-label="Search subjects">
+    <%= submit_tag "Search", name: nil, class: "cs-btn" %>
+    <% if @query.present? %><%= link_to "Clear", subjects_path, class: "cs-btn" %><% end %>
+  <% end %>
+  <span class="cs-spacer"></span>
+</div>
+<% if @query.present? %>
+  <p class="cs-hint">Showing matches for “<%= @query %>” across all subjects. Narrow the list below per page; selection applies to the current page.</p>
+<% elsif @page > 1 || @has_next_page %>
+  <p class="cs-hint">Type to filter this page, or Search to find anyone by email or name across every subject.</p>
+<% end %>
+
+<div class="cs-bulk" data-cs-bulk hidden>
+  <strong><span data-cs-bulk-count>0</span> selected</strong>
+  <span class="cs-spacer"></span>
+  <%# Org-wide role for the selection. JS injects the checked subjects as
+      subject_gids[] on submit; blank role clears it for all. %>
+  <%= form_with url: role_assignment_path, method: :post, class: "cs-bulk-org",
+        data: { cs_bulk_org: true } do %>
+    <%= select_tag :role_id, options_from_collection_for_select(@roles, :id, :name),
+          include_blank: "org role…", aria: { label: "Org-wide role for selected" } %>
+    <%= submit_tag "Set for selected", name: nil, class: "cs-btn" %>
+  <% end %>
+  <%= link_to "Grant scoped role…", "#", class: "cs-btn cs-btn-primary",
+        data: { cs_bulk_scoped: true, cs_bulk_url: new_scoped_role_assignment_path } %>
+  <button type="button" class="cs-btn" data-cs-bulk-clear>Clear</button>
+</div>
+
+<div class="cs-card cs-card--flush">
+<table class="cs-table" data-cs-filter-list>
+  <thead>
+    <tr>
+      <th class="cs-select-cell">
+        <input type="checkbox" data-cs-select-all aria-label="Select all subjects">
+      </th>
+      <th>Subject</th><th>Org-wide role</th><th>Scoped roles</th>
+    </tr>
+  </thead>
+  <tbody>
+    <% @subjects.each do |subject| %>
+      <% key = [ subject.class.name, subject.id ] %>
+      <% label = current_scope_subject_label(subject) %>
+      <%# Filter against a precise text set — subject label, current org role, and
+          scoped roles/records — NOT the row's textContent: every row embeds a
+          <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(" ") %>
+      <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 %>"
+                 aria-label="Select <%= label %>">
+        </td>
+        <td><%= label %></td>
+        <td>
+          <%= form_with url: role_assignment_path, method: :post do %>
+            <%= 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 %>
+          <% 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)}?" %>
+              <%= button_to "×", scoped_role_assignment_path(sra), method: :delete,
+                    class: "cs-chip-remove",
+                    title: "Revoke this scoped role",
+                    form: { data: { cs_confirm: revoke_prompt } },
+                    aria: { label: "Revoke #{sra.role.name} on #{current_scope_label(sra.resource)}" },
+                    data: { turbo_confirm: revoke_prompt } %>
+            </span>
+          <% end %>
+          <%= link_to "+ scoped role", new_scoped_role_assignment_path(subject_gid: subject.to_gid),
+                class: "cs-add-scoped" %>
+        </td>
+      </tr>
+    <% end %>
+  </tbody>
+</table>
+</div>
+
+<p class="cs-filter-empty" data-cs-filter-empty hidden>No subjects on this page match your filter.</p>
+
+<nav class="cs-pagination" aria-label="Subjects pagination">
+  <% if @page > 1 %><%= link_to "← Previous", subjects_path(page: @page - 1, q: @query.presence) %><% end %>
+  <span>Page <%= @page %></span>
+  <% if @has_next_page %><%= link_to "Next →", subjects_path(page: @page + 1, q: @query.presence) %><% end %>
+</nav>

data/app/views/layouts/current_scope/application.html.erb

@@ -0,0 +1,53 @@
+<% cs_theme = %w[light dark].include?(cookies[:current_scope_theme]) ? cookies[:current_scope_theme] : nil %>
+<% active = controller_name %>
+<!DOCTYPE html>
+<html lang="en"<%= " data-cs-theme=\"#{cs_theme}\"".html_safe if cs_theme %>>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>CurrentScope</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= yield :head %>
+
+  <%= stylesheet_link_tag "current_scope/application", media: "all" %>
+  <%= javascript_include_tag "current_scope/application", defer: true %>
+</head>
+<body>
+  <div class="cs-shell">
+    <aside class="cs-sidebar">
+      <div class="cs-brand"><span class="cs-brand-mark" aria-hidden="true"></span> CurrentScope</div>
+      <nav class="cs-nav" aria-label="Management">
+        <%= link_to "Roles", current_scope.roles_path,
+              "aria-current": ("page" if active == "roles") %>
+        <%= link_to "Subjects", current_scope.subjects_path,
+              "aria-current": ("page" if %w[subjects scoped_role_assignments].include?(active)) %>
+        <%= link_to "Events", current_scope.events_path,
+              "aria-current": ("page" if active == "events") %>
+      </nav>
+      <div class="cs-sidebar-foot">Authorization console</div>
+    </aside>
+
+    <div class="cs-main">
+      <div class="cs-topbar">
+        <span class="cs-topbar-title">Authorization</span>
+        <span class="cs-topbar-spacer"></span>
+        <span class="cs-badge">full access</span>
+        <button type="button" class="cs-theme-toggle" data-cs-theme-toggle
+                aria-label="Toggle dark mode" aria-pressed="<%= cs_theme == "dark" %>">
+          <span class="cs-icon-light" aria-hidden="true">☾</span>
+          <span class="cs-icon-dark" aria-hidden="true">☀</span>
+        </button>
+      </div>
+
+      <% if notice.present? %><p class="cs-flash cs-flash--notice" role="status"><%= notice %></p><% end %>
+      <% if alert.present? %><p class="cs-flash cs-flash--alert" role="alert"><%= alert %></p><% end %>
+
+      <main class="cs-content">
+        <%= yield %>
+      </main>
+    </div>
+  </div>
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,14 @@
+CurrentScope::Engine.routes.draw do
+  root to: "roles#index"
+
+  resources :roles, except: :show do
+    member { get :members }
+  end
+  resources :subjects, only: :index
+  resources :events, only: :index
+  resource :role_assignment, only: :create
+  # Remove one org-wide assignment by id (members page: clean up an orphan whose
+  # subject was deleted, which the subject-keyed clear on create can't target).
+  delete "role_assignments/:id" => "role_assignments#destroy", as: :remove_role_assignment
+  resources :scoped_role_assignments, only: [ :new, :create, :destroy ]
+end

data/db/migrate/20260710000001_create_current_scope_tables.rb

@@ -0,0 +1,31 @@
+class CreateCurrentScopeTables < ActiveRecord::Migration[7.1]
+  def change
+    create_table :current_scope_roles do |t|
+      t.string :name, null: false, index: { unique: true }
+      t.boolean :full_access, null: false, default: false
+      t.timestamps
+    end
+
+    create_table :current_scope_role_permissions do |t|
+      t.references :role, null: false, foreign_key: { to_table: :current_scope_roles }
+      t.string :permission_key, null: false
+      t.index [ :role_id, :permission_key ], unique: true
+    end
+
+    create_table :current_scope_role_assignments do |t|
+      t.references :subject, polymorphic: true, null: false,
+                   index: { unique: true, name: "index_current_scope_one_role_per_subject" }
+      t.references :role, null: false, foreign_key: { to_table: :current_scope_roles }
+      t.timestamps
+    end
+
+    create_table :current_scope_scoped_role_assignments do |t|
+      t.references :subject, polymorphic: true, null: false
+      t.references :role, null: false, foreign_key: { to_table: :current_scope_roles }
+      t.references :resource, polymorphic: true, null: false
+      t.timestamps
+      t.index [ :subject_type, :subject_id, :resource_type, :resource_id, :role_id ],
+              unique: true, name: "index_current_scope_unique_scoped_assignment"
+    end
+  end
+end

data/db/migrate/20260710000002_create_current_scope_events.rb

@@ -0,0 +1,32 @@
+class CreateCurrentScopeEvents < ActiveRecord::Migration[7.1]
+  # Append-only authorization event ledger. This migration ships to arbitrary
+  # hosts and is NEVER renamed after release, so the schema shape is FROZEN.
+  #
+  # NORMATIVE target mapping (mirrored in the Event model header):
+  #   - assignment events (org_role.*, scoped_role.*): target = the GRANTEE
+  #     (the subject being granted). The role/resource ride in `details`.
+  #   - role.* events: target = the role itself.
+  def change
+    create_table :current_scope_events do |t|
+      t.string :event, null: false         # namespaced past-tense name (role.created, permission.granted, ...)
+      t.string :actor, null: false         # GlobalID of the REAL actor (never nil: record! raises first)
+      t.string :subject, null: false       # GlobalID of the effective subject; ALWAYS set (== actor unless impersonating)
+      t.string :target, null: false        # GlobalID of the thing acted on (see normative mapping above)
+      t.string :target_label, null: false  # denormalized human label so history survives target deletion
+      # json (NOT jsonb): an opaque, append-only payload the engine never
+      # queries, so it needs no index/operator support — and plain json is the
+      # portable type across SQLite / PostgreSQL / MySQL.
+      t.json :details
+      t.string :request_id                 # correlation-only, not evidence (client-suppliable via X-Request-Id)
+      # created_at only — declared explicitly, NOT via t.timestamps. There is
+      # deliberately no updated_at: its absence documents append-only intent.
+      t.datetime :created_at, null: false
+
+      # Append-only + host-side retention => unbounded growth, so unindexed
+      # scans are forever. Newest-first reads use order(id: :desc) (append-only
+      # => id order == commit order), so no created_at index is needed.
+      t.index :target
+      t.index :actor
+    end
+  end
+end

data/db/migrate/20260714000001_add_description_to_current_scope_roles.rb

@@ -0,0 +1,5 @@
+class AddDescriptionToCurrentScopeRoles < ActiveRecord::Migration[7.1]
+  def change
+    add_column :current_scope_roles, :description, :text
+  end
+end

data/lib/current_scope/configuration.rb

@@ -0,0 +1,181 @@
+module CurrentScope
+  class Configuration
+    # Host controller method that returns the authenticated subject.
+    attr_accessor :user_method
+
+    # Host controller method returning the REAL actor while impersonating
+    # (the pretender's true_user). nil means actor == user (no impersonation),
+    # so the actor is never resolved and falls back to the subject.
+    attr_accessor :actor_method
+
+    # Action names subject to the separation-of-duties veto: whoever initiated
+    # a record can never perform these actions on it. Not editable in the UI
+    # by design — SoD is a structural guarantee, not a preference. Records hit
+    # by these actions must define current_scope_initiator (return nil to
+    # exempt a record type).
+    #
+    # 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
+
+    # Which identities the separation-of-duties veto weighs:
+    #   :either  (default) — veto if the effective subject OR (while
+    #                        impersonating) the REAL actor initiated the record,
+    #                        so impersonation can never approve the actor's own
+    #                        record.
+    #   :subject           — veto only on the effective subject.
+    # The two are identical when not impersonating (actor == subject).
+    attr_accessor :sod_identity
+
+    # When false (the default), an impersonated session is read-only: any
+    # non-GET/HEAD request is denied while a real actor acts as a different
+    # subject — INCLUDING the engine's own management UI. The host's
+    # stop-impersonation, sign-out, and sign-in endpoints must opt out with
+    # skip_before_action :current_scope_mutation_guard!, or impersonation can
+    # never end. The gate runs BEFORE the permission check, so sod_identity is
+    # only observable once mutations are allowed (or on a GET-listed sod_action).
+    #
+    # Setting this true is refused in production unless the env opt-in below is
+    # set — letting a real actor write as someone else is a privilege-escalation
+    # and audit-integrity risk, so a prod deploy must acknowledge it explicitly.
+    # See the custom writer.
+    attr_reader :allow_mutations_while_impersonating
+
+    # Env var that opts a PRODUCTION deploy into impersonated writes. Any value
+    # (even "false" or "0" — presence is what counts) lifts the production
+    # refusal; unset in production means allow_mutations_while_impersonating=true
+    # raises at boot. development/test/staging never consult it.
+    PROD_MUTATIONS_ENV = "CURRENT_SCOPE_ALLOW_PROD_IMPERSONATION_MUTATIONS"
+
+    # Regexps matched against controller paths to keep infrastructure
+    # 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.
+    attr_accessor :excluded_controllers
+
+    # Class the management UI's controllers inherit from, so they pick up the
+    # host's authentication and layout.
+    attr_accessor :parent_controller
+
+    # Host class acting as the subject, used by the management UI to list
+    # assignable subjects.
+    attr_accessor :subject_class
+
+    # How a subject is identified in the management UI (subjects table, picker,
+    # bulk bar). A subject id is meaningless with UUID keys, so pick something
+    # human. Accepts:
+    #   - a Symbol — a method on the subject, e.g. :email or :name
+    #   - a Proc   — subject -> String, e.g. ->(u) { "#{u.first_name} #{u.last_name}" }
+    #   - nil (default) — best-effort, people-first: email, else name, else
+    #     first+last, else the generic current_scope_label / "Class #id".
+    attr_accessor :subject_label
+
+    # Break-glass override for the SoD veto. Default false — OFF preserves v0.1
+    # exactly: the separation-of-duties veto is absolute and this hook is never
+    # consulted. When true, the veto is lifted for a record ONLY when all three
+    # hold, re-checked live at decision time: this flag is on, the record's
+    # `current_scope_sod_bypassed?` hook returns true, AND the record's initiator
+    # holds the bypass permission (sod_bypass_permission). Every lifted veto is
+    # recorded by the engine (`sod.bypassed`) and surfaced on
+    # X-Current-Scope-Reason.
+    #
+    # HONEST FRAMING: this converts SoD from a *structural* guarantee into an
+    # *audited policy override* — it's break-glass, not SoD. Its legitimacy rests
+    # on being default-off, privilege-gated, and always audited. Unlike
+    # allow_mutations_while_impersonating there is NO production env-gate: the
+    # feature is per-record, privilege-scoped, and audited-by-construction, so
+    # production is its intended home.
+    attr_accessor :allow_sod_bypass
+
+    # The grantable permission the record's initiator must hold for a break-glass
+    # bypass to lift the veto (default "bypass_sod"). Resolved against the
+    # record's route key like any permission, so it's editable in the role grid —
+    # never a hardcoded role. Must NOT be listed in sod_actions (it isn't an SoD
+    # action; keeping it out also bounds the bypass re-entrancy).
+    attr_accessor :sod_bypass_permission
+
+    # Tri-state: false | true (default) | :strict — controls
+    # CurrentScope::Event.record!.
+    #   false   — record! is a silent no-op; hosts that don't want the ledger
+    #             set this and skip the events migration.
+    #   true    — append a row for every event; if the current_scope_events
+    #             table hasn't been migrated yet, degrade gracefully (skip +
+    #             warn once), so an existing host never breaks on first mutation.
+    #   :strict — an audit-mandatory host: a missing events table RAISES instead
+    #             of degrading, so a mutation-wrapping transaction rolls back
+    #             rather than committing an unaudited grant. (Impersonation-
+    #             boundary events have no mutation to roll back — a raise there
+    #             is a loud 500 on a mis-migrated host.)
+    # Read as `== :strict`, never `== true` — don't flatten the tri-state.
+    attr_accessor :audit
+
+    # A5 (opt-in, dev/test aid): when true, the gate logs a nudge if an SoD
+    # action is gated with a nil record and the request is allowed — i.e. the
+    # SoD veto was silently skipped because current_scope_record returned nil on
+    # a member action. Off by default; prod behavior never changes. Emitted from
+    # the Guard seam (not the shared resolver), so it doesn't fire on advisory
+    # allowed_to?/scope_for calls.
+    attr_accessor :warn_on_nil_sod_record
+
+    # How the role-editor grid folds RESTful actions into columns. An ordered
+    # Hash of { column_label => [action names] }: ticking a group column grants
+    # every routed action in it. The default collapses the seven RESTful verbs
+    # into CRUD — new/create and edit/update pair up (the "new"/"edit" actions
+    # just render the form for their mutation), index+show read as one. Actions
+    # not in any group (e.g. "approve") get their own column. Set to nil (or {})
+    # to show every raw action as its own column instead. Either way the grid
+    # renders ALIGNED columns — a controller that doesn't route a column's
+    # actions shows a blank cell, never a shifted one.
+    attr_accessor :permission_grid_groups
+
+    def initialize
+      @user_method = :current_user
+      @actor_method = nil
+      @sod_actions = []
+      @sod_identity = :either
+      @allow_sod_bypass = false
+      @sod_bypass_permission = "bypass_sod"
+      @allow_mutations_while_impersonating = false
+      @excluded_controllers = [
+        %r{\Arails/}, %r{\Aactive_storage/}, %r{\Aaction_mailbox/},
+        %r{\Aturbo/}, %r{\Acurrent_scope/}
+      ]
+      @parent_controller = "::ApplicationController"
+      @subject_class = "User"
+      @audit = true
+      @warn_on_nil_sod_record = false
+      @permission_grid_groups = {
+        "read"    => %w[index show],
+        "create"  => %w[new create],
+        "update"  => %w[edit update],
+        "destroy" => %w[destroy]
+      }
+    end
+
+    # Guarded writer: enabling impersonated writes is fine in
+    # development/test/staging, but refused in production unless PROD_MUTATIONS_ENV
+    # is set — so an unsafe flag fails the deploy loudly at boot instead of
+    # silently letting a real actor mutate data as someone else. Assigning false
+    # (or leaving the default) is always allowed.
+    def allow_mutations_while_impersonating=(value)
+      if value && production? && !ENV.key?(PROD_MUTATIONS_ENV)
+        raise ConfigurationError,
+              "config.allow_mutations_while_impersonating = true is refused in " \
+              "production: letting a real actor write as the subject they " \
+              "impersonate is a privilege-escalation and audit-integrity risk. " \
+              "Keep it false so impersonated sessions stay read-only in " \
+              "production, or — only if writes under act-as are genuinely " \
+              "required (e.g. a live public showcase) — set ENV[\"#{PROD_MUTATIONS_ENV}\"] " \
+              "to opt in explicitly. development, test, and staging are unaffected."
+      end
+      @allow_mutations_while_impersonating = value
+    end
+
+    private
+
+    def production?
+      defined?(Rails) && Rails.respond_to?(:env) && Rails.env.production?
+    end
+  end
+end

data/lib/current_scope/context.rb

@@ -0,0 +1,36 @@
+module CurrentScope
+  # Include in ApplicationController (before Guard). Populates the ambient
+  # context from the host's authentication once per request and exposes
+  # allowed_to? to actions and views. CurrentAttributes resets itself around
+  # every request and job, so nothing leaks between executions.
+  module Context
+    extend ActiveSupport::Concern
+    include Permissions
+
+    included do
+      before_action :set_current_scope_user
+      if respond_to?(:helper_method)
+        helper_method :allowed_to?, :scope_for, :current_scope_user, :current_scope_actor, :impersonating?
+      end
+    end
+
+    private
+
+    def set_current_scope_user
+      CurrentScope::Current.user = resolve_current_scope_subject(CurrentScope.config.user_method)
+
+      # nil actor_method means no impersonation: leave actor unset so Current
+      # 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
+    end
+
+    def resolve_current_scope_subject(method)
+      return send(method) if respond_to?(method, true)
+
+      raise CurrentScope::ConfigurationError,
+            "#{self.class.name} does not respond to ##{method}. Define it, or point the " \
+            "matching CurrentScope.config.*_method at your method."
+    end
+  end
+end

data/lib/current_scope/engine.rb

@@ -0,0 +1,14 @@
+module CurrentScope
+  class Engine < ::Rails::Engine
+    isolate_namespace CurrentScope
+
+    # 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,
+    # ahead of eager-load, so the registry rebuilds cleanly.
+    config.to_prepare do
+      CurrentScope.reset_catalog!
+      CurrentScope.reset_scopeable_registry!
+    end
+  end
+end

data/lib/current_scope/gating_tripwire.rb

@@ -0,0 +1,53 @@
+module CurrentScope
+  # A4: an opt-in dev/test tripwire that catches an action which completed
+  # WITHOUT being gated by Guard's current_scope_check!. Include it on a base
+  # controller you want verified — INCLUDING one that never includes Guard (an
+  # API base, a hand-rolled ActionController::Base), which is exactly the
+  # ungated case Guard's own after_action could never see.
+  #
+  #   class ApiController < ActionController::Base
+  #     include CurrentScope::GatingTripwire
+  #     current_scope_skip_tripwire! only: :health   # mark genuinely-public actions
+  #   end
+  #
+  # It owns its skip API on purpose: it can NOT reuse
+  # `skip_before_action :current_scope_check!`, because on a controller that
+  # never included Guard that callback is undefined and skip_before_action
+  # raises ArgumentError at class load — self-defeating on the very controllers
+  # the tripwire targets. `current_scope_skip_tripwire!` skips the tripwire's own
+  # after_action instead.
+  #
+  # Known blind spot: an after_action does not run when a before_action halts the
+  # chain (render/redirect) — so an action that renders straight from a
+  # before_action escapes the tripwire. It is a strong dev/test aid, not total
+  # coverage (Grape/Rack endpoints are out of reach for the same reason).
+  module GatingTripwire
+    extend ActiveSupport::Concern
+
+    included do
+      after_action :current_scope_verify_gated!
+    end
+
+    class_methods do
+      # The tripwire's OWN exempt marker. Accepts the usual callback filters
+      # (only:/except:) and simply skips the tripwire after_action for them.
+      def current_scope_skip_tripwire!(**options)
+        skip_after_action :current_scope_verify_gated!, **options
+      end
+    end
+
+    private
+
+    def current_scope_verify_gated!
+      # Guard sets @current_scope_checked when current_scope_check! runs. A
+      # controller carrying only this mixin (no Guard) never sets it.
+      return if instance_variable_defined?(:@current_scope_checked) && @current_scope_checked
+
+      raise CurrentScope::ConfigurationError,
+            "\"#{controller_path}##{action_name}\" completed without running current_scope_check! — " \
+            "this controller is not gated by CurrentScope::Guard. Include CurrentScope::Guard on its " \
+            "base controller, or mark this action public with " \
+            "`current_scope_skip_tripwire! only: :#{action_name}`."
+    end
+  end
+end

data/lib/current_scope/guard.rb

@@ -0,0 +1,97 @@
+module CurrentScope
+  # The enforcement point. Include after Context to gate every action behind
+  # its own permission: the current controller#action IS the permission key,
+  # so new controllers are gated (fail-closed) the moment they exist.
+  #
+  # Member actions that need record-level decisions (scoped roles, SoD)
+  # declare a private current_scope_record method returning the record. Three
+  # rules for the hook:
+  #   - it runs for EVERY gated action, collection actions included — return
+  #     nil when there is no record
+  #   - it runs BEFORE the controller's own before_actions, so it must load
+  #     the record itself (memoize so set_* callbacks reuse it)
+  #   - key off request.path_parameters, NEVER params: a query-string ?id=
+  #     must not let a scoped role on one record unlock a collection action
+  #
+  #       def current_scope_record
+  #         set_report if request.path_parameters[:id]
+  #       end
+  #
+  # Skip the gate for public endpoints with skip_before_action :current_scope_check!.
+  # MutationGuard (included here) adds the read-only-while-impersonating gate as
+  # its OWN before_action, so it runs first and survives that skip.
+  module Guard
+    extend ActiveSupport::Concern
+    include MutationGuard
+
+    included do
+      before_action :current_scope_check!
+    end
+
+    private
+
+    def current_scope_check!
+      # Record that the gate ran, so an optional GatingTripwire (A4) can tell a
+      # gated action from one on a controller that never included Guard.
+      @current_scope_checked = true
+      permission = "#{controller_path}##{action_name}"
+
+      # An excluded controller can never be granted in the grid, so gating it
+      # would lock it to full_access forever — a misconfiguration, not a deny.
+      unless CurrentScope.catalog.include?(permission)
+        raise CurrentScope::ConfigurationError,
+              "\"#{permission}\" is not in the permission catalog (excluded_controllers " \
+              "or not routed). Either stop excluding it, or skip the gate here with " \
+              "skip_before_action :current_scope_check!."
+      end
+
+      record = respond_to?(:current_scope_record, true) ? send(:current_scope_record) : nil
+
+      # The real actor (Current.actor) enters here explicitly — the resolver
+      # never reads Current itself (PDP purity). It only matters under SoD
+      # :either while impersonating; otherwise actor == subject.
+      allowed, reason = CurrentScope.resolver.decide(
+        subject: CurrentScope::Current.user, permission: permission,
+        record: record, actor: CurrentScope::Current.actor
+      )
+      raise CurrentScope::AccessDenied.new(permission, reason: reason) unless allowed
+
+      record_sod_bypass(permission, record) if reason == :sod_bypassed
+      nudge_on_nil_sod_record(permission, record)
+    end
+
+    # Break-glass audit (KTD-1): the resolver stays pure and only reports
+    # :sod_bypassed; the Guard — which runs once per REAL gated action, never on
+    # advisory allowed_to?/scope_for — records the override exactly once and
+    # surfaces it on the response. Recorded for ANY verb: the guarantee is
+    # "every bypass is audited", so if a host ever routes an SoD action to GET,
+    # the bypass still leaves its trail rather than slipping through unlogged.
+    # Event.record! is a no-op when config.audit is false, so an audit-off host
+    # still permits, records nothing — consistent with the rest of the ledger.
+    def record_sod_bypass(permission, record)
+      initiator = record.send(CurrentScope::Resolver::INITIATOR_METHOD)
+      CurrentScope::Event.record!(
+        event: "sod.bypassed", target: record,
+        details: { permission: permission, initiator: initiator&.to_gid&.to_s }
+      )
+      response.set_header("X-Current-Scope-Reason", "sod_bypassed")
+    end
+
+    # A5 dev/test aid (opt-in): the request was ALLOWED, but if it's an SoD
+    # action gated with a nil record, the SoD veto was silently skipped — a sign
+    # current_scope_record returned nil on a member action. Lives here (the gate
+    # seam), not in the shared resolver, so it never fires on advisory
+    # allowed_to?/scope_for calls. Prod behavior is unchanged either way.
+    def nudge_on_nil_sod_record(permission, record)
+      return unless CurrentScope.config.warn_on_nil_sod_record
+      return unless record.nil?
+      return unless CurrentScope.config.sod_actions.include?(permission.split("#").last)
+
+      Rails.logger&.warn(
+        "[CurrentScope] \"#{permission}\" is a separation-of-duties action but was gated with a " \
+        "nil record, so the SoD veto was skipped. If this is a member action, current_scope_record " \
+        "must return the record; if it's a collection action, this is expected."
+      )
+    end
+  end
+end