RubyGems - current_scope - Versions diffs - 0.2.0 → 0.3.0 - Mend

current_scope 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (35) hide show

checksums.yaml +4 -4
data/README.md +317 -18
data/app/assets/javascripts/current_scope/application.js +4 -0
data/app/assets/stylesheets/current_scope/application.css +99 -0
data/app/controllers/current_scope/application_controller.rb +39 -1
data/app/controllers/current_scope/role_assignments_controller.rb +14 -14
data/app/controllers/current_scope/roles_controller.rb +6 -2
data/app/helpers/current_scope/application_helper.rb +168 -12
data/app/models/current_scope/current.rb +24 -0
data/app/models/current_scope/event.rb +10 -6
data/app/models/current_scope/role.rb +61 -10
data/app/views/current_scope/roles/edit.html.erb +92 -4
data/app/views/current_scope/roles/members.html.erb +3 -3
data/app/views/current_scope/roles/new.html.erb +1 -1
data/app/views/current_scope/scoped_role_assignments/new.html.erb +12 -3
data/app/views/current_scope/shared/access_denied.html.erb +30 -0
data/app/views/current_scope/subjects/index.html.erb +17 -5
data/app/views/layouts/current_scope/application.html.erb +4 -1
data/config/routes.rb +3 -4
data/lib/current_scope/configuration.rb +378 -16
data/lib/current_scope/engine.rb +7 -0
data/lib/current_scope/gating_reflection.rb +62 -0
data/lib/current_scope/gating_tripwire.rb +36 -5
data/lib/current_scope/guard.rb +406 -8
data/lib/current_scope/mutation_guard.rb +30 -5
data/lib/current_scope/permission_catalog.rb +116 -3
data/lib/current_scope/permission_grid.rb +34 -4
data/lib/current_scope/permissions.rb +42 -8
data/lib/current_scope/resolver.rb +317 -13
data/lib/current_scope/version.rb +1 -1
data/lib/current_scope.rb +113 -5
data/lib/generators/current_scope/install/install_generator.rb +64 -0
data/lib/generators/current_scope/install/templates/initializer.rb +94 -5
data/lib/tasks/current_scope_tasks.rake +153 -0
metadata +6 -2

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

@@ -14,7 +14,10 @@
 </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 %>
+<% else %>
+  <%# Always shown (not just on multi-page lists): the one input drives TWO
+      mechanisms — typing live-filters this page, Search queries every subject —
+      and nothing but this line says so. %>
   <p class="cs-hint">Type to filter this page, or Search to find anyone by email or name across every subject.</p>
 <% end %>
@@ -23,8 +26,11 @@
   <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 %>
+  <%# Setting REPLACES each subject's current org-wide role (blank clears it) —
+      as consequential as Remove, which confirms, so this does too. %>
+  <% bulk_prompt = "Change the org-wide role for the selected subjects? This replaces their current role." %>
+  <%= form_with url: role_assignments_path, method: :post, class: "cs-bulk-org",
+        data: { cs_bulk_org: true, cs_confirm: bulk_prompt, turbo_confirm: bulk_prompt } 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" %>
@@ -46,7 +52,11 @@
   </thead>
   <tbody>
     <% @subjects.each do |subject| %>
-      <% key = [ subject.class.name, subject.id ] %>
+      <%# Key by what the polymorphic association STORES (the base_class name),
+          not subject.class.name — an STI subject (AdminUser < User) is saved as
+          "User", and keying on the subclass name would show its roles as
+          "— none —" while the resolver happily enforces them. %>
+      <% key = [ subject.class.polymorphic_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
@@ -61,7 +71,9 @@
         </td>
         <td><%= label %></td>
         <td>
-          <%= form_with url: role_assignment_path, method: :post do %>
+          <% set_prompt = "Change the org-wide role for #{label}? This replaces their current role." %>
+          <%= form_with url: role_assignments_path, method: :post,
+                data: { cs_confirm: set_prompt, turbo_confirm: set_prompt } 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),

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

@@ -15,6 +15,9 @@
   <%= javascript_include_tag "current_scope/application", defer: true %>
 </head>
 <body>
+  <%# WCAG 2.4.1: every page repeats the sidebar + topbar before its content —
+      keyboard users get a bypass. Visually hidden until focused. %>
+  <a class="cs-skip-link" href="#cs-main-content">Skip to content</a>
   <div class="cs-shell">
     <aside class="cs-sidebar">
       <div class="cs-brand"><span class="cs-brand-mark" aria-hidden="true"></span> CurrentScope</div>
@@ -44,7 +47,7 @@
       <% 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">
+      <main class="cs-content" id="cs-main-content" tabindex="-1">
         <%= yield %>
       </main>
     </div>

data/config/routes.rb CHANGED Viewed

@@ -6,9 +6,8 @@ CurrentScope::Engine.routes.draw do
   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
+  # create is subject-keyed (no id); destroy removes one assignment by id (the
+  # members page's cleanup path for an orphan whose subject was deleted).
+  resources :role_assignments, only: [ :create, :destroy ]
   resources :scoped_role_assignments, only: [ :new, :create, :destroy ]
 end

data/lib/current_scope/configuration.rb CHANGED Viewed

@@ -26,7 +26,30 @@ module CurrentScope
     #                        record.
     #   :subject           — veto only on the effective subject.
     # The two are identical when not impersonating (actor == subject).
-    attr_accessor :sod_identity
+    # See the validating writer below — an unknown value must not silently
+    # narrow the veto.
+    attr_reader :sod_identity
+    SOD_IDENTITY_MODES = %i[either subject].freeze
+    # 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
+    # assignment naming the closed set; the previous mode stands.
+    def sod_identity=(value)
+      mode = value.respond_to?(:to_sym) ? value.to_sym : value
+      unless SOD_IDENTITY_MODES.include?(mode)
+        raise ConfigurationError,
+              "config.sod_identity = #{value.inspect} is not a mode. " \
+              "Use :either (default — the veto binds the effective subject AND, " \
+              "while impersonating, the real actor, so impersonation can never " \
+              "approve the actor's own record) or :subject (weigh only the " \
+              "effective subject)."
+      end
+      @sod_identity = mode
+    end
     # 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
@@ -42,10 +65,11 @@ module CurrentScope
     # 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.
+    # Env var that opts a PRODUCTION deploy into impersonated writes. The VALUE
+    # is what counts: a truthy value ("1", "true", "yes"…) lifts the production
+    # refusal; unset, "", "false", "0", "off" all mean "not opted in" — an
+    # operator writing `…=false` in a deploy manifest gets what they said, not
+    # the opposite. development/test/staging never consult it.
     PROD_MUTATIONS_ENV = "CURRENT_SCOPE_ALLOW_PROD_IMPERSONATION_MUTATIONS"
     # Regexps matched against controller paths to keep infrastructure
@@ -69,6 +93,15 @@ module CurrentScope
     #   - 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".
+    #
+    # A Proc should be TOTAL — it runs for every subject the admin can see,
+    # including ones with nil or blank attributes, so `->(u) { u.email.upcase }`
+    # is a trap the first time someone is invited but hasn't filled in an email.
+    # Nothing here is load-bearing enough to break a page over, so a label that
+    # raises (or a Symbol the subject can't answer) degrades to the default chain
+    # for that subject and logs once — it never errors the page and never affects
+    # an authorization decision. If subject labels look wrong, check the log:
+    # a silent fallback is exactly what a broken label looks like from the UI.
     attr_accessor :subject_label
     # Break-glass override for the SoD veto. Default false — OFF preserves v0.1
@@ -93,8 +126,97 @@ module CurrentScope
     # 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).
+    #
+    # It isn't a routable action, so the catalog injects it rather than deriving
+    # it: the grid shows a column for it ONLY when allow_sod_bypass is on, and
+    # only on controllers that route an action listed in sod_actions. With the
+    # flag off it isn't grantable at all — nothing to tick, and the key is
+    # rejected if assigned. (#21)
     attr_accessor :sod_bypass_permission
+    # Action names whose RECORD-LESS gate derives its answer from the scoped
+    # list (#65): for these, the check asks scope_for — the same id-narrowed
+    # query the list renders from — so a scoped full_access grant opens
+    # exactly the collections that would show it records, and gate and list
+    # agree by construction. Matched like sod_actions, on the action segment
+    # of the key ("index" in "reports#index").
+    #
+    # DEFAULT ["index"] — the #65 fix is on out of the box. Set [] to restore
+    # the pre-#65 record-less semantics (never a released posture on their
+    # own — #19/#50/#65 ship together): explicit ticks still open type-bound
+    # record-less gates, a scoped full_access role opens none, and the
+    # gate/list disagreement #65 describes comes back with it.
+    #
+    # LIST-NARROWING READS ONLY. The full_access safety argument is that the
+    # answer is derived from record ids — WHICH records the subject holds —
+    # so it is only sound for actions with a list side. Naming a mutating or
+    # non-idempotent action here ("create", "destroy_all") hands scoped
+    # full_access holders that action on the whole TYPE off a grant on one
+    # record: the #49 escalation, reintroduced by config. Custom read-shaped
+    # actions (export, search) are the intended additions.
+    #
+    # The declared current_scope_model is trusted here the way
+    # current_scope_record already is — a wrong declaration plus a scoped
+    # full_access grant of the declared type opens that controller's listed
+    # 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:
+    #
+    #   - a full KEY ("reports#index") RAISES — the list is matched on the
+    #     action segment and applies to every controller, so a keyed member
+    #     can never match (silently inert) and stripping it to "index" would
+    #     silently widen a deliberately controller-scoped intent. Neither
+    #     reading is honest; say so at assignment.
+    #   - a canonical mutating action name (create/update/destroy) WARNS —
+    #     the #49 escalation shape, reintroduced by config. A warning, not a
+    #     raise: custom action names make any blocklist partial, and the
+    #     report-mode precedent (warn_report_mode_in_production) is the
+    #     house style for "legal but almost certainly not what you meant".
+    #   - an element that is not a String/Symbol RAISES — Array({ index: true })
+    #     is [[:index, true]], and .to_s on that pair is "[:index, true]": a
+    #     member that can never match, silently REPLACING the default and
+    #     un-fixing #65 with no signal (0.3.0 release-gate finding). Only
+    #     action names have an unambiguous string form; anything else says so
+    #     at assignment.
+    def collection_read_actions=(value)
+      elements = Array(value)
+      if (bad = elements.reject { |e| e.is_a?(String) || e.is_a?(Symbol) }).any?
+        raise ConfigurationError,
+              "config.collection_read_actions takes action NAMES (strings or symbols); got " \
+              "#{bad.map(&:inspect).join(', ')}. A Hash or nested array would coerce to a " \
+              "member that can never match an action, silently restoring the pre-#65 " \
+              "record-less semantics. Write e.g. %w[index export]."
+      end
+      actions = elements.map(&:to_s)
+      if (keyed = actions.grep(/#/)).any?
+        raise ConfigurationError,
+              "config.collection_read_actions is matched on the ACTION segment of a key and " \
+              "applies to every controller that routes it — #{keyed.map(&:inspect).join(', ')} " \
+              "can never match. Write \"index\", not \"reports#index\"; there is no " \
+              "per-controller form of this list."
+      end
+      warn_on_mutating_collection_reads(actions)
+      # Frozen so in-place mutation (config.collection_read_actions << :export)
+      # cannot bypass the writer — a symbol appended in place would silently
+      # never match, a "#" key would dodge the raise, and a mutating name would
+      # dodge the warning. FrozenError is loud; assign a new list instead.
+      @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
     # Tri-state: false | true (default) | :strict — controls
     # CurrentScope::Event.record!.
     #   false   — record! is a silent no-op; hosts that don't want the ledger
@@ -108,16 +230,91 @@ module CurrentScope
     #             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.
+    # See the validating writer below — a misspelled :strict must not silently
+    # downgrade an audit-mandatory host to best-effort.
+    attr_reader :audit
+    AUDIT_MODES = [ false, true, :strict ].freeze
+    # Validating writer, same contract as enforcement=: because record! checks
+    # `== :strict`, a typo (`:strixt`) is truthy and would silently behave as
+    # plain true — the host believes unaudited mutations roll back while they
+    # commit. Raise at assignment naming the closed set; the previous mode
+    # stands.
+    def audit=(value)
+      # ENV can only carry strings, and two of the three modes are booleans —
+      # normalize the boolean spellings before symbolizing ("strict" → :strict).
+      mode = case value
+      when "true" then true
+      when "false" then false
+      else value.respond_to?(:to_sym) ? value.to_sym : value
+      end
+      unless AUDIT_MODES.include?(mode)
+        raise ConfigurationError,
+              "config.audit = #{value.inspect} is not a mode. " \
+              "Use false (record! is a silent no-op — no ledger), " \
+              "true (append a row per event, degrade gracefully if the events " \
+              "table is missing), or :strict (a missing events table RAISES so " \
+              "a mutation-wrapping transaction rolls back rather than " \
+              "committing an unaudited grant)."
+      end
+      @audit = mode
+    end
+    # --- Dev diagnostics (#41) ----------------------------------------------
+    #
+    # Four failure modes this engine has that are SILENT and silent in the bad
+    # direction: the thing that went wrong looks exactly like the thing going
+    # right. Each is a cheap log line in dev/test and costs nothing in prod.
+    #
+    # All four default ON in development and test, OFF in production — and off
+    # entirely when Rails isn't loaded. The default is the point: a diagnostic
+    # nobody knows about is a diagnostic nobody benefits from, and these
+    # protect against mistakes you make while WRITING the app, which is exactly
+    # when dev/test is where you are. A host can force any of them either way.
+    #
+    # Every one is LOG-ONLY. No decision, exception, header, or audit row
+    # changes because of them, in any environment.
+    # The gate logs a nudge when an SoD action is gated with no record and the
+    # request is ALLOWED — i.e. the veto was skipped because current_scope_record
+    # returned nil (or was never declared) on a member action. The gem's #1
+    # foot-gun: the veto silently not running looks identical to the veto passing.
+    #
+    # Emitted from the Guard seam (not the shared resolver), so it never fires on
+    # advisory allowed_to?/scope_for calls.
     attr_accessor :warn_on_nil_sod_record
+    # The gate logs a nudge when a request is DENIED :no_grant, the controller
+    # declared no current_scope_record hook at all, and the subject holds a
+    # scoped grant that WOULD have applied had the hook returned the record.
+    #
+    # That combination is a controller with member actions that forgot the hook.
+    # It fails closed — correctly — but the 403 is indistinguishable from "you
+    # were never granted this", so the person debugging it goes looking at their
+    # grants, which are fine, instead of at their controller, which isn't.
+    attr_accessor :warn_on_inert_scoped_grant
+    # CurrentScope.permission_key logs a nudge when short-form derivation
+    # (`allowed_to?(:show, report)`) resolves to a DIFFERENT key than the one the
+    # current controller's gate enforces — the documented namespaced/custom-named
+    # controller foot-gun. The view then shows a link that 403s, or hides one that
+    # would have worked: the gate and the view disagree, silently, and the symptom
+    # shows up nowhere near the cause.
+    attr_accessor :warn_on_cross_controller_derivation
+    # The gate logs a nudge when a request is DENIED :model_undeclared — a
+    # declared collection action (current_scope_record returned nil) whose
+    # controller names no current_scope_model, while the subject holds a scoped
+    # grant ticking the key. The record-less branch had no type to bind that
+    # grant to, so it failed closed (#50) — correctly, but the 403 looks like
+    # "never granted" while the fix is one line in the controller. The same
+    # flag gates the :model_invalid nudge — the hook was declared but returned
+    # something unusable ("Report" for Report); one failure family, one knob.
+    attr_accessor :warn_on_undeclared_collection_model
     # 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
@@ -129,6 +326,84 @@ module CurrentScope
     # actions shows a blank cell, never a shifted one.
     attr_accessor :permission_grid_groups
+    # :enforce (default) | :report — what the gate DOES with a denial. (#37)
+    #
+    # The adoption ramp. A host retrofitting this engine onto an existing app
+    # has a controller suite that goes red the moment the gate is mounted: it is
+    # fail-closed, and nothing is granted yet. Report mode lets them mount the
+    # gate, run their app, and read what WOULD have been denied out of the
+    # ledger — turning a big-bang cutover into a list of grants to seed.
+    #
+    #   :enforce — deny means 403. The only production posture.
+    #   :report  — a MISSING GRANT is logged and allowed through instead. Every
+    #              other denial still refuses.
+    #
+    # Report mode is NOT an off switch and never reaches the things that would
+    # make it one: the separation-of-duties veto still refuses, and the
+    # management console answers to its own full-access check rather than this
+    # gate, so no enforcement setting can hand out the UI where grants are made.
+    attr_reader :enforcement
+    ENFORCEMENT_MODES = %i[enforce report].freeze
+    # Validating writer: an unknown value here is the worst kind of config
+    # mistake — the host believes it is enforcing while it is not. Fail at boot,
+    # naming what's allowed. Accepts a String so ENV["..."] works; anything that
+    # can't be a mode (nil from an unset ENV var, a number, a collection) raises
+    # ConfigurationError rather than NoMethodError, and the previous mode stands.
+    def enforcement=(value)
+      mode = value.respond_to?(:to_sym) ? value.to_sym : value
+      unless ENFORCEMENT_MODES.include?(mode)
+        raise ConfigurationError,
+              "config.enforcement = #{value.inspect} is not a mode. " \
+              "Use :enforce (deny means 403 — the production posture) or " \
+              ":report (log what WOULD be denied and allow it through, to seed " \
+              "grants before cutting over). Report mode is for adoption only: " \
+              "it never lifts the separation-of-duties veto and never opens the " \
+              "management console."
+      end
+      warn_report_mode_in_production if mode == :report && production?
+      @enforcement = mode
+    end
+    # True only in report mode. A predicate, so callers can't express "not
+    # enforcing" — the modes are a closed set, not a boolean.
+    def report_only? = @enforcement == :report
+    # :raise | :warn — what the opt-in GatingTripwire mixin (A4) does when it
+    # catches an action that completed without running the gate.
+    #
+    #   :raise — fail loudly. Default in development/test: an ungated action is
+    #            a hole you want CI to go red on, not one to discover in an audit.
+    #   :warn  — log once per controller#action and let the response through, so
+    #            a real app can inventory its ungated surface without 500ing.
+    #
+    # A closed two-mode set, like enforcement — not a boolean, and no :off:
+    # not including the mixin is off.
+    attr_reader :gating_tripwire
+    GATING_TRIPWIRE_MODES = %i[raise warn].freeze
+    # Validating writer, same contract as enforcement=: an unknown value raises
+    # at assignment naming both modes, and the previous mode stands. Accepts a
+    # String so ENV["..."] works.
+    def gating_tripwire=(value)
+      mode = value.respond_to?(:to_sym) ? value.to_sym : value
+      unless GATING_TRIPWIRE_MODES.include?(mode)
+        raise ConfigurationError,
+              "config.gating_tripwire = #{value.inspect} is not a mode. " \
+              "Use :raise (an ungated action fails loudly — the dev/test posture) " \
+              "or :warn (log it once per controller#action and let the response " \
+              "through, to inventory an app's ungated surface). There is no :off — " \
+              "not including CurrentScope::GatingTripwire is off."
+      end
+      @gating_tripwire = mode
+    end
     def initialize
       @user_method = :current_user
       @actor_method = nil
@@ -136,6 +411,7 @@ module CurrentScope
       @sod_identity = :either
       @allow_sod_bypass = false
       @sod_bypass_permission = "bypass_sod"
+      @collection_read_actions = [ "index" ].freeze
       @allow_mutations_while_impersonating = false
       @excluded_controllers = [
         %r{\Arails/}, %r{\Aactive_storage/}, %r{\Aaction_mailbox/},
@@ -144,7 +420,18 @@ module CurrentScope
       @parent_controller = "::ApplicationController"
       @subject_class = "User"
       @audit = true
-      @warn_on_nil_sod_record = false
+      @enforcement = :enforce
+      # Reuses diagnostics_default_on? for its env split and bare-Ruby safety
+      # ONLY — do NOT carry over the diagnostics flags' emit/silence reading.
+      # There, false means stay quiet; here, false means :warn, which EMITS.
+      # The inversion is deliberate: the tripwire mixin is opt-in, so a
+      # production host that included it is asking for the ungated inventory —
+      # the env decides only whether a hit 500s (dev/test) or logs (elsewhere).
+      @gating_tripwire = diagnostics_default_on? ? :raise : :warn
+      @warn_on_nil_sod_record = diagnostics_default_on?
+      @warn_on_inert_scoped_grant = diagnostics_default_on?
+      @warn_on_cross_controller_derivation = diagnostics_default_on?
+      @warn_on_undeclared_collection_model = diagnostics_default_on?
       @permission_grid_groups = {
         "read"    => %w[index show],
         "create"  => %w[new create],
@@ -159,7 +446,7 @@ module CurrentScope
     # 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)
+      if value && production? && !prod_mutations_opt_in?
         raise ConfigurationError,
               "config.allow_mutations_while_impersonating = true is refused in " \
               "production: letting a real actor write as the subject they " \
@@ -167,13 +454,88 @@ module CurrentScope
               "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."
+              "to a truthy value (\"1\"/\"true\") to opt in explicitly; \"false\", " \
+              "\"0\", and empty mean not opted in. development, test, and staging " \
+              "are unaffected."
       end
       @allow_mutations_while_impersonating = value
     end
     private
+    # The env var's VALUE means what it says — presence alone is not consent.
+    # ActiveModel's boolean cast maps "false"/"0"/"f"/"off" to false and "" to
+    # nil; anything else present is truthy. Only reached when production? is
+    # already true, so Rails (and ActiveModel) are loaded — a bare-Ruby
+    # Configuration.new never gets here.
+    def prod_mutations_opt_in?
+      !!ActiveModel::Type::Boolean.new.cast(ENV[PROD_MUTATIONS_ENV])
+    end
+    # Report mode in production is DELIBERATELY allowed — surveying real traffic
+    # is the most honest way to find out what to grant, and a staging run won't
+    # show you the flows your actual users take. Refusing it here would break the
+    # feature's best use case.
+    #
+    # But "we are not enforcing authorization" is not a state a production app
+    # should be in silently, or for long. The failure mode is quiet: nothing
+    # breaks, no one is refused, and the temporary survey becomes the permanent
+    # posture because nothing ever reminded anyone. So it says so at boot, once,
+    # where a deploy log will keep it.
+    #
+    # ponytail: a warn, not a raise. Unlike allow_mutations_while_impersonating
+    # (which has an env-gate refusal) this has a legitimate production use and a
+    # deliberate exit — the host is mid-migration, and the loud reminder is the
+    # right amount of friction.
+    def warn_report_mode_in_production
+      message = "[CurrentScope] config.enforcement = :report in PRODUCTION — " \
+                "authorization is NOT being enforced. Missing grants are logged " \
+                "as access.would_deny and the request is ALLOWED THROUGH. This is " \
+                "an adoption ramp, not a production posture: seed the grants the " \
+                "ledger names, then set config.enforcement = :enforce."
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.warn(message)
+      else
+        # Boot order: an initializer can run before the logger exists. Say it
+        # anyway — a warning nobody sees is the thing this method exists to
+        # prevent.
+        warn(message)
+      end
+    end
+    # Mirrors warn_report_mode_in_production: a legal posture that is almost
+    # never what the host meant says so once, loudly, where a boot log keeps
+    # it. Warn in every env — unlike report mode this misconfiguration is as
+    # wrong in development as in production.
+    def warn_on_mutating_collection_reads(actions)
+      mutating = actions & MUTATING_ACTION_NAMES
+      return if mutating.empty?
+      message = "[CurrentScope] config.collection_read_actions includes " \
+                "#{mutating.map(&:inspect).join(', ')} — this list is for LIST-NARROWING READS. " \
+                "A mutating action here hands scoped full_access holders that action on every " \
+                "record of its type off a grant on ONE record (the #49 escalation shape). " \
+                "Remove it unless that is genuinely intended."
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.warn(message)
+      else
+        warn(message)
+      end
+    end
+    # Diagnostics are on where you are while writing the app, off where they'd
+    # be noise on someone else's dime. `local?` is Rails' own name for
+    # "development or test", so a host with a staging env that reports itself as
+    # neither gets prod behaviour — the conservative side for a log line.
+    #
+    # Mirrors the production? guard below: a bare-Ruby Configuration.new with no
+    # Rails must not raise, and gets false (no logger to warn to anyway).
+    def diagnostics_default_on?
+      defined?(Rails) && Rails.respond_to?(:env) && Rails.env.local?
+    end
     def production?
       defined?(Rails) && Rails.respond_to?(:env) && Rails.env.production?
     end

data/lib/current_scope/engine.rb CHANGED Viewed

@@ -9,6 +9,13 @@ module CurrentScope
     config.to_prepare do
       CurrentScope.reset_catalog!
       CurrentScope.reset_scopeable_registry!
+      # The cross-controller nudge warns once per site; a reload can change what's
+      # routed, so a stale latch would hide a divergence the edit just created.
+      CurrentScope.reset_cross_controller_warnings!
+      # Same reason for the tripwire's :warn latch: a reload can change whether a
+      # controller#action is gated, and a stale latch would hand a dev running
+      # :warn a false all-clear right after the edit.
+      CurrentScope::GatingTripwire.reset_warnings!
     end
   end
 end

data/lib/current_scope/gating_reflection.rb ADDED Viewed

@@ -0,0 +1,62 @@
+module CurrentScope
+  # Answers one question about a controller path: is it PROVEN that
+  # current_scope_check! never runs there? True only when the callback is
+  # ABSENT from the class's callback chain — the one thing the chain states
+  # unconditionally. Everything else is false:
+  #
+  #   - callback present and unconditional → gated → false
+  #   - callback present wearing a condition (skip_before_action only:) →
+  #     UNPROVABLE without evaluating ActionFilter internals, which this class
+  #     must never do (KTD-3) → false. The naive any?/none? presence check
+  #     inverts exactly here — see the ProblemFrame characterization in
+  #     test/gating_reflection_test.rb — and per-action guessing is how a
+  #     fail-open gets reported as gated.
+  #   - no controller class routed at that path → nothing to prove → false
+  #
+  # Absence is an EFFECT, not a cause: a bare skip_before_action, an inherited
+  # bare skip (#62), and never including Guard at all are the same verdict,
+  # because the chain looks the same. That is deliberate — the question is
+  # "does the gate run?", not "why not?".
+  #
+  # Named beside GatingTripwire: both interrogate the same subject (is this
+  # action gated?), the tripwire at request time, this one by reflection.
+  class GatingReflection
+    def ungated?(controller_path)
+      klass = controller_class_for(controller_path)
+      # A controller without the callbacks API at all (a bare ActionController::
+      # Metal without AbstractController::Callbacks) cannot run a before_action
+      # — the gate PROVABLY never runs there. Without this check the reflection
+      # would raise NoMethodError instead of answering. (#79 review)
+      return true unless klass.respond_to?(:_process_action_callbacks)
+      klass
+        ._process_action_callbacks
+        .none? { |callback| callback.kind == :before && callback.filter == :current_scope_check! }
+    rescue ActionDispatch::MissingController
+      # A routed path with no controller class (a scaffolding leftover, a
+      # not-yet-written controller) proves nothing about gating. Silent false,
+      # matching the prove-or-stay-silent discipline of
+      # warn_on_cross_controller_derivation.
+      false
+    end
+    private
+    # Rails owns the path→class rule — camelize, namespacing, the Controller
+    # suffix, and crucially the NameError triage: a missing CONTROLLER constant
+    # becomes MissingController (rescued above), while a NameError raised from
+    # inside the controller's own broken body re-raises as-is and must
+    # PROPAGATE out of ungated? (a blanket rescue NameError would silently
+    # report a broken controller as gated). Hand-rolling camelize+constantize
+    # would have to reimplement that triage and would drift. (KTD-2)
+    #
+    # controller_class_for lives on Request, so a throwaway request object is
+    # the price of asking. Built lazily and memoized here, NEVER in initialize:
+    # the role-save path constructs a GatingReflection it may never ask — any
+    # failure in construction would 500 role saves. (KTD-8)
+    def controller_class_for(controller_path)
+      @request ||= ActionDispatch::Request.new({})
+      @request.controller_class_for(controller_path)
+    end
+  end
+end