current_scope 0.3.0 → 0.4.0

data/lib/current_scope/guard.rb

@@ -115,7 +115,9 @@ module CurrentScope
         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!."
+              "skip_before_action :current_scope_check!. Skipping the gate leaves this " \
+              "controller ungated by CurrentScope — protect it with your own " \
+              "authorization (e.g. require_admin!)."
       end
 
       record = resolve_current_scope_record
@@ -134,8 +136,10 @@ module CurrentScope
       CurrentScope::Current.collection_model = record.equal?(NO_RECORD) ? nil : model
       CurrentScope::Current.collection_model_path = controller_path
 
-      # The real actor (Current.actor) enters here explicitly — the resolver
-      # never reads Current itself (PDP purity). It only matters under SoD
+      # Decision *inputs* (subject, permission, record, model, actor) are
+      # explicit — the resolver does not read ambient identity for the allow/
+      # deny answer. Org-role *lookup* may use Current.memoized_org_role (a
+      # per-request cache, not a decision input). Actor only widens SoD under
       # :either while impersonating; otherwise actor == subject.
       allowed, reason = CurrentScope.resolver.decide(
         subject: CurrentScope::Current.user, permission: permission,
@@ -156,8 +160,19 @@ module CurrentScope
 
         return report_would_deny(permission, record) if report_only_denial?(reason, permission, record)
 
-
-        raise CurrentScope::AccessDenied.new(permission, reason: reason)
+        # Report mode still 403s the SoD blind spot (correct, fail-closed) but
+        # used to do so silently — no log, no ledger, invisible to
+        # current_scope:report. Diagnose before the raise so a retrofit host
+        # sees the mis-declared record hook they must fix (#73).
+        diagnose_report_sod_blind_spot(permission, record, reason)
+
+        raise CurrentScope::AccessDenied.new(
+          permission,
+          reason: reason,
+          permission: permission,
+          record: (record.equal?(NO_RECORD) ? nil : record),
+          subject: CurrentScope::Current.user
+        )
       end
 
       record_sod_bypass(permission, record) if reason == :sod_bypassed
@@ -231,6 +246,57 @@ module CurrentScope
       record_would_deny_event(permission, record)
     end
 
+    # #73: report mode refuses to *downgrade* an SoD blind-spot denial (the
+    # veto never ran), but must not 403 *silently*. Log the cause/fix and
+    # record a distinct ledger row — never access.would_deny, because granting
+    # the permission will not clear this 403 (the hook is the fix).
+    def diagnose_report_sod_blind_spot(permission, record, reason)
+      return unless CurrentScope.config.report_only?
+      return unless reason == :no_grant
+      # Ask the resolver (#74) — no second copy of the skip condition.
+      return unless sod_veto_blind_spot?(permission, record)
+
+      Rails.logger&.warn(
+        "[CurrentScope] report-only: DENIED #{permission.inspect} because the " \
+        "separation-of-duties veto could not run (no usable record for this " \
+        "action). This is NOT a missing grant — granting will not clear the 403. " \
+        "Declare current_scope_record to return the AR record on this member " \
+        "action (or remove the action from config.sod_actions if it is not " \
+        "meant to be four-eyes gated). See also rails current_scope:report " \
+        "(access.sod_blind_spot events)."
+      )
+      record_sod_blind_spot_event(permission, record)
+    end
+
+    def record_sod_blind_spot_event(permission, record)
+      subject = CurrentScope::Current.user
+      return if subject.nil?
+
+      target = record.equal?(NO_RECORD) ? nil : record
+      # Non-records (String params[:id], etc.) are not GlobalID targets.
+      target = nil unless target.respond_to?(:to_gid)
+
+      CurrentScope::Event.record!(
+        event: "access.sod_blind_spot",
+        target: target || subject,
+        details: {
+          permission: permission,
+          reason: "no_grant",
+          blind_spot: true,
+          fix: "declare current_scope_record for this SoD member action"
+        }
+      )
+    rescue StandardError => e
+      # Blind-spot path returns 403 next — do not claim the request was allowed
+      # or that a would_deny row was lost (PR #103 review).
+      warn_ledger_failure_once(
+        e,
+        event: "access.sod_blind_spot",
+        request_outcome: "The request was DENIED (403) — only the access.sod_blind_spot row is missing."
+      )
+      nil
+    end
+
     # R3: report mode NEVER raises — that is its whole promise, and it has to hold
     # regardless of audit posture or the state of the ledger.
     #
@@ -265,7 +331,11 @@ module CurrentScope
     rescue StandardError => e
       # ponytail: swallow and warn ONCE. An unrecordable observation is a lost
       # log line; a raise here is a 500 on a request report mode promised to pass.
-      warn_ledger_failure_once(e)
+      warn_ledger_failure_once(
+        e,
+        event: "access.would_deny",
+        request_outcome: "The request WAS allowed through — only the access.would_deny row is missing."
+      )
       nil
     end
 
@@ -281,13 +351,18 @@ module CurrentScope
     # fix for a missing table and otherwise reports the real error, because
     # telling someone with a dead connection to run migrations sends them after
     # the wrong problem.
-    def warn_ledger_failure_once(error)
+    #
+    # `event` / `request_outcome` are path-specific: would_deny allows the
+    # request; sod_blind_spot still 403s — the operator-facing text must not
+    # claim the wrong outcome (PR #103).
+    def warn_ledger_failure_once(error, event:, request_outcome:)
       return if CurrentScope::Guard.ledger_warning_emitted?
 
       CurrentScope::Guard.ledger_warning_emitted!
-      Rails.logger&.warn("[CurrentScope] report-only: #{ledger_failure_hint(error)} " \
-                         "The request WAS allowed through — only the access.would_deny " \
-                         "row is missing. This warns once per process.")
+      Rails.logger&.warn(
+        "[CurrentScope] report-only: #{ledger_failure_hint(error, event: event)} " \
+        "#{request_outcome} This warns once per process."
+      )
     end
 
     # ASKS Event whether this is the un-migrated-table case rather than pattern-
@@ -296,14 +371,14 @@ module CurrentScope
     # says why: it "would point operators at the wrong fix". A looser test here
     # reintroduced exactly that, telling someone their table was missing while
     # they were looking right at it. (#59 review)
-    def ledger_failure_hint(error)
+    def ledger_failure_hint(error, event:)
       if CurrentScope::Event.missing_events_table?(error)
-        "the current_scope_events table is missing, so would-be denials are not being " \
-        "recorded and `rails current_scope:report` will be empty. Run " \
+        "the current_scope_events table is missing, so #{event} rows are not being " \
+        "recorded and `rails current_scope:report` will be incomplete. Run " \
         "`rails current_scope:install:migrations && rails db:migrate`, or set " \
         "config.audit = false if you don't want the ledger."
       else
-        "could not record a would-be denial (#{error.class}: #{error.message.to_s.truncate(120)})."
+        "could not record #{event} (#{error.class}: #{error.message.to_s.truncate(120)})."
       end
     end
 
@@ -384,9 +459,22 @@ module CurrentScope
       return unless CurrentScope.config.warn_on_inert_scoped_grant
       return unless reason == :no_grant
       return unless record.equal?(NO_RECORD)
-      return unless CurrentScope.resolver.scoped_grant_exists?(
-        subject: CurrentScope::Current.user, permission: permission
-      )
+
+      # Diagnostics must not 500 the request (#74): a transient DB error inside
+      # scoped_grant_exists? is log-only, matching record_would_deny_event.
+      has_grant =
+        begin
+          CurrentScope.resolver.scoped_grant_exists?(
+            subject: CurrentScope::Current.user, permission: permission
+          )
+        rescue StandardError => e
+          Rails.logger&.warn(
+            "[CurrentScope] warn_on_inert_scoped_grant could not check scoped grants " \
+            "(#{e.class}: #{e.message}); skipping diagnostic for \"#{permission}\"."
+          )
+          false
+        end
+      return unless has_grant
 
       # Says only what the predicate proves. scoped_grant_exists? has no resource
       # filter — it can't have one, the missing record IS the bug — so it
@@ -479,16 +567,23 @@ module CurrentScope
 
     def nudge_on_nil_sod_record(permission, record)
       return unless CurrentScope.config.warn_on_nil_sod_record
-      # NO_RECORD counts: it IS the member-action-with-no-record case this nudge
-      # exists to catch, so it must not go quiet just because the Guard now
-      # labels that case instead of passing a bare nil.
-      return unless record.nil? || record.equal?(NO_RECORD)
-      return unless CurrentScope.config.sod_actions.include?(permission.split("#").last)
+      # Ask the resolver (#74) — do not re-derive "did the veto skip?". A private
+      # nil/NO_RECORD copy missed the commonest mistake: a hook returning
+      # params[:id] (a String). sod_veto_skipped? is the single definition.
+      gate_record = record.equal?(NO_RECORD) ? nil : record
+      return unless CurrentScope.resolver.sod_veto_skipped?(permission: permission, record: gate_record)
+
+      shape_hint =
+        if gate_record.nil?
+          "a nil record"
+        else
+          "a non-record (#{gate_record.class.name}) — often a hook returning params[:id]"
+        end
 
       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."
+        "[CurrentScope] \"#{permission}\" is a separation-of-duties action but was gated with " \
+        "#{shape_hint}, so the SoD veto was skipped. If this is a member action, " \
+        "current_scope_record must return the AR record; if it's a collection action, this is expected."
       )
     end
   end

data/lib/current_scope/mutation_guard.rb

@@ -31,8 +31,12 @@ module CurrentScope
       return if CurrentScope.config.allow_mutations_while_impersonating
       return unless current_scope_impersonating?
 
+      key = "#{controller_path}##{action_name}"
       raise CurrentScope::AccessDenied.new(
-        "#{controller_path}##{action_name}", reason: :impersonation_gate
+        key,
+        reason: :impersonation_gate,
+        permission: key,
+        subject: CurrentScope::Current.user
       )
     end
 
@@ -55,6 +59,12 @@ module CurrentScope
     def current_scope_denied(exception = nil)
       reason = exception.respond_to?(:reason) ? exception.reason : nil
       response.headers["X-Current-Scope-Reason"] = reason.to_s if reason
+      # Mirror the header into the server log so log-based triage can distinguish
+      # no_grant from sod_veto without reading response headers (#39).
+      permission = exception.respond_to?(:permission) ? exception.permission : nil
+      Rails.logger&.info(
+        "[CurrentScope] denied #{permission || '(unknown)'} (#{reason || 'unknown'}) → 403"
+      )
       current_scope_render_denied(reason)
     end
 

data/lib/current_scope/permissions.rb

@@ -60,17 +60,6 @@ module CurrentScope
     # default — the class form allowed_to?(:index, Report) is how you ask about
     # another controller, and it binds from its argument (R5). (KTD-6)
     #
-    # The match keys on the KEY's controller, not just the controller: kwarg: a
-    # full "reports#index" key from a projects view names "reports" and must NOT
-    # borrow the projects ambient (a Project grant answering a reports key). A
-    # bare action uses the resolved controller. (#50 review, cubic)
-    def ambient_collection_model(action, controller)
-      key_controller = action.to_s.include?("#") ? action.to_s.split("#").first : controller
-      return nil unless key_controller && key_controller == CurrentScope::Current.collection_model_path
-
-      CurrentScope::Current.collection_model
-    end
-
     def current_scope_user
       CurrentScope::Current.user
     end
@@ -87,5 +76,19 @@ module CurrentScope
     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

data/lib/current_scope/resolver.rb

@@ -266,15 +266,11 @@ module CurrentScope
 
       # Re-entrancy is bounded ONLY because the bypass permission isn't itself an
       # SoD action (KTD-5) — the inner allowed? below returns at the SoD step
-      # without recursing. Enforce that invariant loudly rather than trusting the
-      # host to honor the doc comment: a bypass action in sod_actions would
-      # recurse to a SystemStackError.
-      bypass_action = CurrentScope.config.sod_bypass_permission.to_s.split("#").last
-      if CurrentScope.config.sod_actions.include?(bypass_action)
-        raise ConfigurationError,
-              "config.sod_bypass_permission (#{CurrentScope.config.sod_bypass_permission.inspect}) is the " \
-              "action #{bypass_action.inspect}, which is also in config.sod_actions. The bypass permission " \
-              "must not be an SoD action — it would recurse. Remove #{bypass_action.inspect} from sod_actions."
+      # without recursing. Boot validate! is the primary gate (#40); this raise
+      # is defense in depth for runtime-mutated config (tests reassign live).
+      # The conflict test lives on Configuration so boot and decide cannot drift.
+      if CurrentScope.config.sod_bypass_permission_conflicts_with_sod_actions?
+        CurrentScope.config.validate!
       end
 
       # Absent hook ⇒ this type never breaks glass (fail-closed, no raise).

data/lib/current_scope/version.rb

@@ -1,3 +1,3 @@
 module CurrentScope
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/current_scope.rb

@@ -14,9 +14,20 @@ require "current_scope/engine"
 
 module  CurrentScope
   # Raised when the resolver denies an action gated by Guard (or when the
-  # management UI is accessed without a full-access role). Carries an optional
-  # machine-readable reason, surfaced on the response as X-Current-Scope-Reason
-  # by current_scope_denied:
+  # management UI is accessed without a full-access role). Accessors:
+  #
+  #   #permission — denied key (stable API for branded 403s). Defaults to the
+  #                 positional message when permission: is omitted so legacy
+  #                 raise sites still populate it. Prefer this over #message.
+  #   #message    — StandardError message (positional arg). Gem raise sites pass
+  #                 the key as both message and permission; they can diverge if
+  #                 a caller passes an explicit permission: keyword.
+  #   #reason     — machine-readable cause (also on X-Current-Scope-Reason)
+  #   #record     — the record under decision when the gate had one; nil for
+  #                 collection / impersonation-gate denials
+  #   #subject    — effective subject when known; nil if none was in scope
+  #
+  # Reasons surfaced by current_scope_denied:
   #
   #   :sod_veto           — the record's initiator can't perform an SoD action on it
   #   :no_grant           — nothing granted the permission (the default deny)
@@ -34,11 +45,16 @@ module  CurrentScope
   # denial cannot exist that forgets its reason. (:sod_bypassed is the one
   # audited ALLOW, so it is set by the Guard rather than raised here.)
   class AccessDenied < StandardError
-    attr_reader :reason
+    attr_reader :reason, :permission, :record, :subject
 
-    def initialize(message = nil, reason: nil)
+    def initialize(message = nil, reason: nil, permission: nil, record: nil, subject: nil)
       super(message)
       @reason = reason
+      # permission defaults to message so older raise sites and branded-403
+      # recipes that only pass the key positionally still populate #permission.
+      @permission = permission || message
+      @record = record
+      @subject = subject
     end
   end
 
@@ -190,12 +206,43 @@ module  CurrentScope
     # Seeds the default Owner/Member roles ONLY on the default path — the name
     # promises "assign a role", so a caller granting an explicit role must not
     # get a full-access Owner row created in their roles table as a side effect.
+    #
+    # Audit (#30): when the org role actually changes, records one
+    # `org_role.assigned` / `org_role.changed` event, self-attributed to the
+    # grantee with `details.source = "bootstrap"`. Same-role re-grants are a
+    # no-op event-wise. Direct model writes and TestHelpers do not go through
+    # this path and are not recorded (documented intentionally).
     def grant!(subject, role: nil)
       role ||= begin
         seed_defaults!
         Role.find_by!(name: "Owner")
       end
-      RoleAssignment.find_or_initialize_by(subject: subject).tap { |a| a.update!(role: role) }
+
+      RoleAssignment.transaction do
+        assignment = RoleAssignment.find_or_initialize_by(subject: subject)
+        prior_role = assignment.persisted? ? assignment.role : nil
+        assignment.update!(role: role)
+
+        if prior_role.nil?
+          Event.record!(
+            event: "org_role.assigned",
+            target: subject,
+            details: { role: role.name, source: "bootstrap" },
+            actor: subject,
+            subject: subject
+          )
+        elsif prior_role.id != role.id
+          Event.record!(
+            event: "org_role.changed",
+            target: subject,
+            details: { from: prior_role.name, to: role.name, source: "bootstrap" },
+            actor: subject,
+            subject: subject
+          )
+        end
+
+        assignment
+      end
     end
 
     private

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

@@ -110,8 +110,10 @@ CurrentScope.configure do |config|
 
   # Audit ledger — tri-state: false | true (default) | :strict.
   #   false   — no audit rows recorded.
-  #   true    — record every authorization change; if the events table hasn't
-  #             been migrated yet, degrade gracefully (skip + warn once).
+  #   true    — record management-UI mutations, impersonation boundary events,
+  #             and grant!/rake/seeds bootstrap grants; if the events table
+  #             hasn't been migrated yet, degrade gracefully (skip + warn once).
+  #             Direct model writes and test helpers are not recorded.
   #   :strict — a missing events table RAISES (rolling the mutation back), so an
   #             audit-mandatory app never commits an unaudited change.
   # config.audit = true
@@ -159,6 +161,9 @@ CurrentScope.configure do |config|
   # Controller paths (regexps) excluded from the permission grid. Excluded
   # controllers can't be granted, so they must also skip the gate with
   # skip_before_action :current_scope_check! — Guard raises otherwise.
+  # Skipping the gate leaves the controller ungated by CurrentScope — protect
+  # it with your own authorization (e.g. require_admin!). See
+  # https://github.com/davidteren/current_scope/blob/main/docs/SECURITY-CHECKLIST.md
   # config.excluded_controllers += [%r{\Awebhooks/}]
 
   # Controller the management UI inherits from (for host auth + before_actions).

data/lib/tasks/current_scope_tasks.rake

@@ -9,6 +9,14 @@ namespace :current_scope do
     subject = klass.find_by(id: id)
     abort "No #{klass} with id=#{id}" if subject.nil?
 
+    # grant! seeds Owner on the default path — warn on replacement even when
+    # the Owner row does not exist yet (first-time Owner creation).
+    prior = CurrentScope::RoleAssignment.find_by(subject: subject)&.role
+    if prior && prior.name != "Owner"
+      warn "WARNING: #{klass}##{subject.id} already held the #{prior.name.inspect} role — " \
+           "replacing it with full-access Owner."
+    end
+
     CurrentScope.grant!(subject)
     puts "Granted the full-access Owner role to #{klass}##{subject.id}."
   end
@@ -32,6 +40,10 @@ namespace :current_scope do
     begin
       rows = CurrentScope::Event.where(event: "access.would_deny")
                                 .pluck(:subject, :target_label, :details)
+      # #73: SoD blind-spot 403s are NOT would_deny (granting won't fix them).
+      # Surface them as a separate section so the survey is complete.
+      blind_rows = CurrentScope::Event.where(event: "access.sod_blind_spot")
+                                      .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
@@ -42,7 +54,7 @@ namespace :current_scope do
             "Run: bin/rails current_scope:install:migrations && bin/rails db:migrate"
     end
 
-    if rows.empty?
+    if rows.empty? && blind_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
@@ -61,25 +73,42 @@ namespace :current_scope do
     # 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
+    #
+    # Shared tally so would_deny and sod_blind_spot sections cannot drift on
+    # ordering / unknown-permission handling (PR #103 review).
+    print_permission_counts = lambda do |event_rows|
+      event_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)'}" }
+    end
+
+    unless rows.empty?
+      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)}"
+        print_permission_counts.call(subject_rows)
+        puts
+      end
+
+      puts "Total: #{rows.count} would-be denials across #{grouped.size} subject(s)."
     end
 
-    puts "Total: #{rows.count} would-be denials across #{grouped.size} subject(s)."
+    unless blind_rows.empty?
+      puts if rows.any?
+      puts "SoD blind-spot denials — NOT fixed by granting (declare current_scope_record):"
+      puts
+      print_permission_counts.call(blind_rows)
+      puts
+      puts "Total: #{blind_rows.count} blind-spot 403(s). Granting these permissions will not " \
+           "clear them — fix the record hook (or remove the action from config.sod_actions)."
+    end
   end
 
   desc "Inventory the routed controllers that provably never run the gate — the static " \

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: current_scope
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - David Teren