current_scope 0.2.0 → 0.3.0

data/lib/generators/current_scope/install/templates/initializer.rb

@@ -1,4 +1,39 @@
 CurrentScope.configure do |config|
+  # --- Retrofitting an existing app? Start here ---------------------------
+  #
+  # This engine is fail-closed: once the gate is mounted, anything not granted
+  # is denied. In an app that already has users and traffic, that means your
+  # controller suite goes RED and your users get 403s the moment you mount it —
+  # not because anything is misconfigured, but because no grants exist yet.
+  #
+  # So don't cut over blind. Run in report mode first:
+  #
+  #   config.enforcement = :report
+  #
+  # The gate then LOGS what it would have denied and lets the request through.
+  # Exercise the app (or run your suite), then read the gaps back out — each row
+  # names a subject and the permission they were missing:
+  #
+  #   bin/rails current_scope:report
+  #
+  # That list IS your grant-seeding work. Seed the roles it names, watch the
+  # would_deny rows stop appearing, then flip to :enforce. Reversible at every
+  # step — it's one line back.
+  #
+  # Report mode is an ADOPTION ramp, not a way to run in production. It relaxes
+  # exactly one thing: "nobody has granted this yet". A separation-of-duties
+  # veto still refuses, and the management console is never opened by it.
+  #
+  # config.enforcement = :enforce   # :enforce (default) | :report
+  # ------------------------------------------------------------------------
+
+  # What the opt-in GatingTripwire mixin does when it catches an action that
+  # completed WITHOUT running the gate. :raise fails loudly (CI goes red);
+  # :warn logs once per controller#action and lets the response through, so a
+  # real app can inventory its ungated surface without 500ing. There is no
+  # :off — not including CurrentScope::GatingTripwire is off.
+  # config.gating_tripwire = Rails.env.local? ? :raise : :warn
+
   # Controller method that returns the authenticated subject.
   # config.user_method = :current_user
 
@@ -17,6 +52,26 @@ CurrentScope.configure do |config|
   # config.permission_grid_groups = { "read" => %w[index show], "create" => %w[new create],
   #                                   "update" => %w[edit update], "destroy" => %w[destroy] }
 
+  # Action names whose record-less gate derives its answer from the scoped
+  # list: for these, "may they open this list?" is answered by the same
+  # id-narrowed query scope_for renders from, so a scoped full_access role
+  # ("Owner of Report #7") opens exactly the collections that would show it
+  # records — gate and list agree by construction. Matched on the action
+  # segment of the key, like sod_actions. Default ["index"]; set [] to
+  # restore the pre-#65 behavior (explicit ticks still open type-bound
+  # record-less gates; scoped full_access opens none). A full key
+  # ("reports#index") raises — the list is action-segment matched, app-wide —
+  # and a canonical mutating name (create/update/destroy) warns at assignment.
+  #
+  # LIST-NARROWING READS ONLY: the safety of honoring full_access here comes
+  # from the answer being derived from record ids, so it is only sound for
+  # actions with a list side. Never name a mutating action ("create",
+  # "destroy_all") — that would hand a scoped full_access holder the action
+  # on every record of the type off a grant on one record. Custom read
+  # actions (export, search) are the intended additions. The declared
+  # current_scope_model is trusted like current_scope_record: review both.
+  # config.collection_read_actions = %w[index]
+
   # --- Impersonation (act-as) ---------------------------------------------
   # These three knobs layer, in this order:
   #
@@ -61,11 +116,45 @@ CurrentScope.configure do |config|
   #             audit-mandatory app never commits an unaudited change.
   # config.audit = true
 
-  # Dev/test aid: log a nudge when an SoD action is ALLOWED but was gated with a
-  # nil record — i.e. the SoD veto was silently skipped because
-  # current_scope_record returned nil on a member action. Off by default; never
-  # changes behavior.
-  # config.warn_on_nil_sod_record = false
+  # --- Dev diagnostics -----------------------------------------------------
+  # Four failure modes this engine has that are SILENT, and silent in the bad
+  # direction — the thing going wrong looks exactly like the thing going right.
+  # All four are LOG-ONLY (no decision, exception, header, or audit row changes)
+  # and all four default ON in development and test, OFF in production.
+  #
+  # They are listed here rather than left to the docs on purpose: a named flag in
+  # your initializer is how you learn the failure mode exists at all.
+
+  # The SoD veto was SKIPPED because the gate had no record — an SoD member
+  # action whose current_scope_record returned nil (or was never declared). The
+  # request was ALLOWED, and a skipped veto looks identical to a veto that
+  # passed. The gem's #1 foot-gun.
+  # config.warn_on_nil_sod_record = Rails.env.local?
+
+  # Denied "no_grant", but the subject holds a scoped grant that WOULD have
+  # applied — and the controller declares no current_scope_record, so the gate
+  # had no record to apply it to. A member action that forgot its hook: it fails
+  # closed (correctly), but the 403 is indistinguishable from "never granted", so
+  # you go and stare at the grants, which are fine.
+  # config.warn_on_inert_scoped_grant = Rails.env.local?
+
+  # Short-form allowed_to?(:show, record) derived a DIFFERENT key than the gate
+  # on the current controller enforces (the namespaced/custom-named controller
+  # foot-gun): a link that 403s, or a hidden one that would have worked. A hint,
+  # not an accusation — asking about another resource derives a different key too,
+  # and that's correct — so it warns once per site and names both readings.
+  # config.warn_on_cross_controller_derivation = Rails.env.local?
+
+  # Denied "model_undeclared": a collection action declared with
+  # `current_scope_record = nil` on a controller that names no
+  # current_scope_model, while the subject holds a scoped grant ticking the
+  # key. The gate had no type to bind that grant to, so it failed closed —
+  # correctly, but the fix is one line: `def current_scope_model = TheType`.
+  # The same flag covers "model_invalid" — a declared hook returning
+  # something other than a concrete AR class ("Report" for Report); that
+  # nudge names the value the hook returned.
+  # config.warn_on_undeclared_collection_model = Rails.env.local?
+  # ------------------------------------------------------------------------
 
   # Controller paths (regexps) excluded from the permission grid. Excluded
   # controllers can't be granted, so they must also skip the gate with

data/lib/tasks/current_scope_tasks.rake

@@ -12,4 +12,157 @@ namespace :current_scope do
     CurrentScope.grant!(subject)
     puts "Granted the full-access Owner role to #{klass}##{subject.id}."
   end
+
+  desc "Summarize would-be denials recorded in report mode into a starter role grid. " \
+       "Usage: bin/rails current_scope:report"
+  task report: :environment do
+    # The subject's current org-wide role, when resolvable — the grid reads
+    # differently if someone already holds a role that just doesn't tick these
+    # keys. Best-effort: a rollout aid must not abort everyone else's summary
+    # because one subject's record was deleted or its class no longer loads.
+    # A lambda, not a def — a rake file's `def` lands on Object.
+    org_role_suffix = lambda do |subject_gid|
+      subject = GlobalID::Locator.locate(subject_gid)
+      role = subject && CurrentScope::RoleAssignment.find_by(subject: subject)&.role
+      role ? " — currently #{role.name}" : ""
+    rescue StandardError
+      ""
+    end
+
+    begin
+      rows = CurrentScope::Event.where(event: "access.would_deny")
+                                .pluck(:subject, :target_label, :details)
+    rescue ActiveRecord::StatementInvalid => e
+      # Report mode without the migration records nothing (the ledger degrades and
+      # warns once). Reaching for this summary is exactly how a host discovers
+      # that, so it must name the fix rather than raise a stack trace at them.
+      raise unless e.message.match?(/current_scope_events/i)
+
+      abort "The current_scope_events table doesn't exist, so nothing was recorded.\n" \
+            "Run: bin/rails current_scope:install:migrations && bin/rails db:migrate"
+    end
+
+    if rows.empty?
+      # "No output" is indistinguishable from "the task is broken", and the two
+      # likeliest causes are both SILENT: report mode never on, or audit off.
+      # Name them — this is the first thing a host runs, and an unexplained blank
+      # is how they conclude the feature doesn't work.
+      puts "No would-be denials recorded."
+      puts
+      puts "  config.enforcement is #{CurrentScope.config.enforcement.inspect} " \
+           "(needs :report to record any)"
+      puts "  config.audit is #{CurrentScope.config.audit.inspect} " \
+           "(needs true or :strict — the ledger is where these rows live)"
+      puts
+      puts "With both on, exercise the app or run your suite, then re-run this."
+      next
+    end
+
+    # ponytail: group in Ruby, not SQL. `details` is a JSON column and querying
+    # into it is adapter-specific; this is a rollout aid run by hand over a
+    # transitional table, so portability beats a smarter query.
+    grouped = rows.group_by { |subject, _label, _details| subject }
+
+    puts "Would-be denials — grant these to stop them (most-denied first):"
+    puts
+
+    grouped.each do |subject_gid, subject_rows|
+      label = subject_rows.first[1].presence || subject_gid
+      puts "  #{label}#{org_role_suffix.call(subject_gid)}"
+
+      subject_rows
+        .group_by { |_s, _l, details| details.is_a?(Hash) ? details["permission"] : nil }
+        .transform_values(&:count)
+        .sort_by { |permission, count| [ -count, permission.to_s ] }
+        .each { |permission, count| puts "    #{count.to_s.rjust(5)}x  #{permission || '(unknown)'}" }
+
+      puts
+    end
+
+    puts "Total: #{rows.count} would-be denials across #{grouped.size} subject(s)."
+  end
+
+  desc "Inventory the routed controllers that provably never run the gate — the static " \
+       "half of the ungated-surface audit (config.gating_tripwire = :warn is the runtime half). " \
+       "Usage: bin/rails current_scope:ungated"
+  task ungated: :environment do
+    # One reflection for the whole walk — its request object memoizes (KTD-8).
+    # A broken controller body's NameError propagates on purpose (KTD-2): a
+    # rescue here would report a broken controller as gated.
+    gating = CurrentScope::GatingReflection.new
+    catalog = CurrentScope.catalog
+    grouped = catalog.grouped
+
+    # The catalog injects the break-glass key onto any row routing an SoD
+    # action, and that grant is LIVE even on an ungated controller — honored by
+    # whatever gated controller decides SoD on the record (the grid's own
+    # KTD-9 exemption). Printing it under "grants nothing" would tell an
+    # operator the most sensitive grant in the grid is inert. Strip it from
+    # the listing and say so once. Only the INJECTED key is stripped —
+    # catalog.routed? keeps a real routed action that merely shares the bypass
+    # name in the audit, because omitting it would hide a real fail-open route.
+    # The catalog also owns the permission parse (split("#", -1) + shape
+    # checks) — a loose split here would accept a malformed value. (#79 review)
+    bypass_action = CurrentScope.config.allow_sod_bypass ? catalog.bypass_action : nil
+    stripped_bypass = false
+
+    # Build the printable rows BEFORE deciding emptiness: a synthetic
+    # bypass-only row (a namespace-only SoD resource) reflects as "ungated"
+    # while routing nothing, and a header over an empty body reads as a broken
+    # task. Rows first, then branch on what there is to say.
+    rows = grouped.keys.sort.filter_map { |controller|
+      next unless gating.ungated?(controller)
+
+      actions = grouped[controller].sort
+      if bypass_action && actions.include?(bypass_action) && !catalog.routed?("#{controller}##{bypass_action}")
+        actions -= [ bypass_action ]
+        stripped_bypass = true
+      end
+      next if actions.empty? # nothing routed here — nothing to audit
+
+      [ controller, actions ]
+    }
+
+    if grouped.empty?
+      # A vacuous all-clear is worse than a blank: with nothing routed there
+      # was nothing to inspect, and "every routed controller has the callback"
+      # is technically true of an empty set and completely misleading.
+      puts "No routed controllers found in the permission catalog — nothing was " \
+           "inspected. Check your routes and config.excluded_controllers."
+    elsif rows.empty?
+      # An unexplained blank reads as "the task is broken" — and a bare blank
+      # would also overclaim. Claim only what the reflection proved: nothing
+      # was PROVEN ungated. A route whose controller doesn't resolve is
+      # unclassified, not vouched for (#43 owns that badge) — "every controller
+      # has the callback" would vouch for rows nobody inspected.
+      puts "No controller was proven ungated. (A routed path whose controller " \
+           "does not resolve is unclassified, not verified — see issue #43.)"
+    else
+      puts "Provably ungated — current_scope_check! is absent from these controllers' " \
+           "callback chains, so the gate never runs there:"
+      puts
+      rows.each { |controller, actions| puts "  #{controller} (#{actions.join(', ')})" }
+      puts
+      puts "Ticking these in the role grid grants nothing until the gate runs. " \
+           "If a controller inherited a skip, re-assert before_action " \
+           ":current_scope_check! on it; if it never had the gate, include " \
+           "CurrentScope::Guard."
+      if stripped_bypass
+        puts
+        puts "(#{bypass_action} omitted from the listing — break-glass stays LIVE " \
+             "even on an ungated controller; see the role grid's exempt note.)"
+      end
+    end
+
+    # The limit of the proof, stated even when nothing is listed (KTD-3): a
+    # conditional skip (skip_before_action only:/except:) leaves the callback
+    # PRESENT wearing a condition — unprovable by reflection, so never shown
+    # here even though some of its actions really run open. The runtime half
+    # catches those.
+    puts
+    puts "Limit: this lists only what the callback chain PROVES. A conditional skip " \
+         "(skip_before_action only:/except:) does not appear here — set " \
+         "config.gating_tripwire = :warn and include CurrentScope::GatingTripwire " \
+         "to inventory those at runtime."
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: current_scope
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - David Teren
@@ -32,7 +32,9 @@ dependencies:
 description: 'A mountable Rails engine for authorization: permissions auto-derived
   from controller actions, roles as editable data, per-record scoped roles, a separation-of-duties
   veto, and an ambient authorization context that makes allowed_to? work identically
-  in controllers, views, and components.'
+  in controllers, views, and components. NOT PRODUCTION-READY: pre-1.0 with known
+  issues under active work — good for experimentation and spikes, not yet for real
+  users. See the README and the issue tracker.'
 email:
 - dteren@gmail.com
 executables: []
@@ -64,6 +66,7 @@ files:
 - app/views/current_scope/roles/members.html.erb
 - app/views/current_scope/roles/new.html.erb
 - app/views/current_scope/scoped_role_assignments/new.html.erb
+- app/views/current_scope/shared/access_denied.html.erb
 - app/views/current_scope/subjects/index.html.erb
 - app/views/layouts/current_scope/application.html.erb
 - config/routes.rb
@@ -74,6 +77,7 @@ files:
 - lib/current_scope/configuration.rb
 - lib/current_scope/context.rb
 - lib/current_scope/engine.rb
+- lib/current_scope/gating_reflection.rb
 - lib/current_scope/gating_tripwire.rb
 - lib/current_scope/guard.rb
 - lib/current_scope/mutation_guard.rb