current_scope 0.5.0

data/app/models/current_scope/current.rb

@@ -0,0 +1,74 @@
+module CurrentScope
+  # The ambient authorization context. Request- and job-scoped: Rails resets
+  # CurrentAttributes around every unit of execution, so the subject can never
+  # leak between requests, jobs, or test examples.
+  #
+  # Two identities live here:
+  #   - user  — the EFFECTIVE subject every permission check reads.
+  #   - actor — the REAL principal behind the request (the pretender's
+  #             `true_user`). It falls back to `user`, so attribution always
+  #             reads `actor` with no nil branch. They differ only while
+  #             impersonating: actor = the admin, user = the impersonated subject.
+  class Current < ActiveSupport::CurrentAttributes
+    # request_id is correlation-only metadata the audit recorder stamps onto
+    # each event; nil when the host hasn't set it. Additive — no reader override.
+    attribute :user, :actor, :request_id
+
+    # #50: the collection type the request's controller declared via
+    # current_scope_model, and the controller_path it was declared for. The
+    # Guard stashes both once per request so the advisory path (allowed_to? in
+    # a view) can bind the record-less gate the same way the controller gate
+    # did — but the PATH is stored so a cross-controller advisory question
+    # (allowed_to?(:index, controller: "reports") from a projects view) does
+    # NOT borrow the wrong controller's type (KTD-6). Request-scoped, reset
+    # with everything else, so it never leaks between requests.
+    attribute :collection_model, :collection_model_path
+
+    # Per-request memo for the resolver's org-role lookup. A view with N
+    # permission-gated elements calls the gate N times, each otherwise re-running
+    # the same `RoleAssignment.find_by(subject:)`; caching it here collapses that
+    # to one query. Request/job-scoped like everything on CurrentAttributes, so
+    # it never leaks across requests, and invalidated on any org-role write (see
+    # RoleAssignment) so a grant-then-check within one request is never stale.
+    attribute :org_role_cache
+
+    # Falls back to the effective subject, so actor is never nil when user is
+    # set — callers attribute to `actor` without a nil branch.
+    #
+    # ROUND-TRIP HAZARD: the reader answers with the fallback, not stored
+    # state. Snapshot/restore code (Current.set, Object#with, anything that
+    # reads #actor to write it back) would pin the fallback as an explicit
+    # actor and restore a stale identity once user changes — read the raw
+    # `attributes` hash instead, as TestHelpers#with_current_user does.
+    def actor
+      super || user
+    end
+
+    # True only while a distinct real actor stands behind the effective
+    # subject (act-as). THE definition of "impersonating" — the Permissions
+    # mixin and the mutation guard both delegate here, so the view-level
+    # read-only signal and the write gate can never drift apart.
+    def impersonating?
+      user.present? && actor != user
+    end
+
+    # Memoize the org-role lookup for `subject` for the rest of this request/job.
+    # Keyed by subject so a check that spans several subjects stays correct.
+    # Caches nil (no role) too, so a repeated "no grant" check is one query, not N.
+    def memoized_org_role(subject)
+      return yield if subject.nil?
+
+      cache = (self.org_role_cache ||= {})
+      key = [ subject.class.name, subject.id ]
+      return cache[key] if cache.key?(key)
+
+      cache[key] = yield
+    end
+
+    # Drop the memo — called on any org-role write so a later check in the same
+    # request sees the change.
+    def reset_org_role_cache
+      self.org_role_cache = nil
+    end
+  end
+end

data/app/models/current_scope/event.rb

@@ -0,0 +1,136 @@
+module CurrentScope
+  # Append-only authorization event ledger. Design rules:
+  #
+  #   - Append-only: there is no updated_at; persisted rows are never mutated.
+  #   - Identities and target are stored as GlobalID strings, alongside a
+  #     denormalized `target_label`, so the history outlives the records it
+  #     names (a deleted role still renders in the ledger).
+  #   - `actor` and `subject` are ALWAYS present. subject == actor unless
+  #     impersonating; impersonated rows are exactly the ones where
+  #     subject <> actor.
+  #   - NORMATIVE target mapping: assignment events (org_role.*, scoped_role.*)
+  #     target the GRANTEE (the subject being granted); role.* events target the
+  #     role. Role/resource ride in `details`.
+  #
+  # The AR-level `readonly?` ceiling is honest but NOT total. These BYPASS it:
+  #   update_all / delete_all / update_column(s) / insert_all / raw SQL.
+  # The sandbox reset job (a later unit) is the one sanctioned `delete_all`
+  # caller. DB-level hardening is adapter-honest: REVOKE UPDATE/DELETE covers
+  # PostgreSQL and MySQL hosts; SQLite hosts get file permissions only.
+  # Hash-chain tamper-evidence is deferred.
+  class Event < ApplicationRecord
+    # Once written, a row is immutable — blocks update / save / destroy at the
+    # AR layer. See the class header for the operations that bypass this.
+    def readonly? = persisted?
+
+    class << self
+      # The ONE recording entry point. Reads the ambient actor/subject from
+      # CurrentScope::Current, serializes actor/subject/target as GlobalID
+      # strings, denormalizes a human label for the target, and — when
+      # config.audit is on — appends exactly one row.
+      #
+      #   CurrentScope::Event.record!(event: "role.created", target: role,
+      #                               details: { name: "Owner" })
+      #
+      # Raises ConfigurationError (loud, matching the SoD posture) when there is
+      # no ambient actor and no explicit actor: override. Silent no-op (returns
+      # nil) when config.audit is false.
+      #
+      # Optional actor:/subject: overrides (#30): when non-nil they replace the
+      # ambient reads so bootstrap paths (grant!, rake, seeds) can self-attribute
+      # without a controller. Omit both for byte-for-byte ambient behavior.
+      # Pin BOTH on a self-attributed grant so an ambient Current.user cannot
+      # leak into subject and mis-record the row as impersonation.
+      def record!(event:, target:, details: nil, actor: nil, subject: nil)
+        return unless CurrentScope.config.audit
+
+        actor ||= CurrentScope::Current.actor
+        if actor.nil?
+          raise CurrentScope::ConfigurationError,
+                "CurrentScope::Event.record! has no actor — CurrentScope::Current.actor is nil. " \
+                "Set the ambient context (the controller hook, or with_current_user in tests) before recording."
+        end
+
+        # Explicit subject wins; else Current.user; else actor (never nil when
+        # actor is set, equals actor when not impersonating).
+        subject ||= CurrentScope::Current.user || actor
+
+        # requires_new: on PostgreSQL a StatementInvalid aborts the *whole*
+        # open transaction even if rescued — so a missing events table would
+        # poison grant!/controller mutation transactions that wrap record!.
+        # A savepoint isolates the audit write: default audit=true degrades
+        # and the assignment commits; :strict re-raises and rolls the outer
+        # mutation back (PR #102 review).
+        Event.transaction(requires_new: true) do
+          create!(
+            event: event.to_s,
+            actor: actor.to_gid.to_s,
+            subject: subject.to_gid.to_s,
+            target: target.to_gid.to_s,
+            target_label: label_for(target),
+            details: details,
+            request_id: CurrentScope::Current.request_id
+          )
+        end
+      rescue ActiveRecord::StatementInvalid => e
+        raise unless missing_events_table?(e)
+
+        # :strict — an audit-mandatory host refuses to commit a mutation with no
+        # audit row. Re-raise so the enclosing (mutation-wrapping) transaction
+        # rolls back rather than silently degrading. Checked as `== :strict`, not
+        # `!= true`, so the tri-state can't be flattened by a future refactor.
+        # (Impersonation-boundary events have no DB mutation to roll back, so a
+        # raise there is simply a loud 500 on a mis-migrated host.)
+        raise if CurrentScope.config.audit == :strict
+
+        # true (default) — an existing host that upgrades the gem without running
+        # the new migration must not break on its first mutation. Degrade
+        # gracefully: skip recording and warn once (not on every call), naming
+        # the fix. A host that wants audit runs the migration; one that doesn't
+        # can set config.audit = false to silence it, or :strict to fail loud.
+        warn_missing_events_table_once
+        nil
+      end
+
+      private
+
+      def warn_missing_events_table_once
+        return if @missing_events_table_warned
+
+        @missing_events_table_warned = true
+        Rails.logger&.warn(
+          "[CurrentScope] audit is on but the current_scope_events table is missing — " \
+          "skipping audit recording. Run `rails current_scope:install:migrations` and " \
+          "migrate to enable it, or set `CurrentScope.config.audit = false` to silence this."
+        )
+      end
+
+      # The shared chain (CurrentScope.label_for) — the same label the UI
+      # renders is the one denormalized into target_label, so the ledger and
+      # the screen can't disagree about what a record was called.
+      def label_for(record)
+        CurrentScope.label_for(record)
+      end
+
+      # Recognizes "table is missing" across adapters and Rails' own schema
+      # reflection: SQLite ("no such table" / "Could not find table"),
+      # PostgreSQL ("relation ... does not exist"), MySQL ("Unknown table" /
+      # "doesn't exist"). The `column` exclusion keeps a missing-COLUMN error
+      # (e.g. "column ... of relation current_scope_events does not exist" after
+      # a partial migration) from being misreported as a missing table, which
+      # would point operators at the wrong fix.
+      def missing_events_table?(error)
+        message = error.message
+        message.include?("current_scope_events") &&
+          !message.match?(/\bcolumn\b/i) &&
+          message.match?(/no such table|could not find table|does(?:n't| not) exist|unknown table|undefined table/i)
+      end
+      # PUBLIC: report mode's ledger warning asks this too (#37). It is one
+      # question — "is this the un-migrated-table case?" — and one adapter-shaped
+      # answer, so it gets one definition. A second opinion elsewhere is a second
+      # opinion that drifts, and this one decides which fix an operator is sent
+      # after. (#59 review)
+      public :missing_events_table?
+    end
+  end
+end

data/app/models/current_scope/role.rb

@@ -0,0 +1,106 @@
+module CurrentScope
+  # A named, editable bundle of permissions — a row, not a class. The same
+  # role means the same permission set whether held org-wide or scoped to a
+  # single record; only the reach differs.
+  class Role < ApplicationRecord
+    has_many :role_permissions, dependent: :delete_all
+    has_many :role_assignments, dependent: :destroy
+    has_many :scoped_role_assignments, dependent: :destroy
+
+    validates :name, presence: true, uniqueness: true
+    validate :permission_keys_in_catalog
+
+    after_save :persist_permission_keys
+
+    # The grid diff computed by the last save:
+    # { added: [...], removed: [...], rejected: [...] }. Empty arrays on a no-op
+    # save; nil when no grid was staged (a programmatic save that never set
+    # permission_keys). `added`/`removed` describe what actually persisted;
+    # `rejected` names keys the scrub path threw away, so a caller that opted
+    # into silence can still log it. Controllers read this to record the change
+    # — the model itself records nothing (seeds must stay silent).
+    attr_reader :permission_keys_change
+
+    def grants?(permission_key)
+      role_permissions.exists?(permission_key: permission_key)
+    end
+
+    def permission_keys
+      @pending_permission_keys || role_permissions.pluck(:permission_key)
+    end
+
+    # Stages a replacement permission set. STRICT: a key that isn't in the
+    # route-derived catalog makes the record invalid rather than disappearing.
+    # This is the mass-assignment writer (update!, strong params, the role
+    # grid), so it is deliberately the strict one — the scrub escape hatch must
+    # never be reachable from form params.
+    def permission_keys=(keys)
+      assign_permission_keys(keys, scrub: false)
+    end
+
+    # ponytail: one implementation, two intents — the setter is the strict
+    # front door, this is the same staging with the scrub opt-in named at the
+    # call site.
+    #
+    # `scrub: true` is the ONLY sanctioned silent drop, and it exists for one
+    # real case: a controller was removed, so a role still holds keys that no
+    # longer route. Cleaning those up is legitimate and shouldn't require the
+    # operator to name every dead key. Everything else — typos, unrouted
+    # programmatic grants, the never-routed break-glass permission — is a
+    # mistake, and a security-grant API must not swallow mistakes.
+    def assign_permission_keys(keys, scrub: false)
+      # Literal `true` only. Ruby truthiness would let the string "false" — or
+      # any params/config value that found its way here — silently disable the
+      # strict path, which is the exact hole this API exists to close. The
+      # escape hatch opens for a caller that means it, not for one that passed
+      # something along.
+      @scrub_permission_keys = scrub == true
+      # Blank entries are the grid's hidden-field padding, not typos (R2).
+      @pending_permission_keys = Array(keys).map(&:to_s).reject(&:blank?).uniq
+    end
+
+    def reload(...)
+      @pending_permission_keys = nil
+      @scrub_permission_keys = false
+      super
+    end
+
+    private
+
+    def permission_keys_in_catalog
+      return if @pending_permission_keys.nil? || @scrub_permission_keys
+
+      unknown = @pending_permission_keys.reject { |k| CurrentScope.catalog.include?(k) }
+      return if unknown.empty?
+
+      errors.add(
+        :permission_keys,
+        "not in the permission catalog: #{unknown.join(', ')} — check for typos, or use " \
+        "assign_permission_keys(..., scrub: true) to drop stale keys deliberately"
+      )
+    end
+
+    def persist_permission_keys
+      return if @pending_permission_keys.nil?
+
+      # Capture the prior keys BEFORE delete_all so the diff survives the swap.
+      previous = role_permissions.pluck(:permission_key)
+      # Defense in depth: on the strict path validation already proved every key
+      # is in the catalog, so this filter is a no-op. It is what the scrub path
+      # relies on, and it means no future code path that skips validations
+      # (insert_all, update_column, a bare `save(validate: false)`) can smuggle
+      # an unknown key into the table.
+      staged = @pending_permission_keys.select { |k| CurrentScope.catalog.include?(k) }
+      @permission_keys_change = {
+        added: staged - previous,
+        removed: previous - staged,
+        rejected: @pending_permission_keys - staged
+      }
+
+      role_permissions.delete_all
+      role_permissions.insert_all(staged.map { |k| { permission_key: k } }) if staged.any?
+      @pending_permission_keys = nil
+      @scrub_permission_keys = false
+    end
+  end
+end

data/app/models/current_scope/role_assignment.rb

@@ -0,0 +1,42 @@
+module CurrentScope
+  # A subject's single org-wide role. One per subject by design — the "which
+  # role granted this?" ambiguity of multi-role systems is deliberately
+  # avoided; per-record needs are covered by scoped roles instead.
+  class RoleAssignment < ApplicationRecord
+    belongs_to :role
+    belongs_to :subject, polymorphic: true
+
+    # One org-wide role per subject. Name the rule and the upsert alternative
+    # so a double-grant is a one-line fix, not a trip through gem source (#44).
+    # Base error (not :subject_id) so create! does not prefix "Subject id …".
+    validate :one_org_role_per_subject
+    # #151: a grant must name exactly one record.
+    include CurrentScope::StorableKeys
+    validates_storable_polymorphic_keys "subject"
+
+    def one_org_role_per_subject
+      return if subject_type.blank? || subject_id.blank?
+
+      held = RoleAssignment.where(subject_type: subject_type, subject_id: subject_id)
+      held = held.where.not(id: id) if persisted?
+      existing = held.includes(:role).first
+      return unless existing
+
+      label = existing.role ? %("#{existing.role.name}") : "another role"
+      errors.add(:base,
+        "Subject already holds org-wide role #{label}; use CurrentScope.grant! " \
+        "to replace, or scoped roles for additive access")
+    end
+    private :one_org_role_per_subject
+
+    # Bust the per-request org-role memo (CurrentScope::Current) whenever an
+    # assignment changes, so a grant/clear and a later gate check in the SAME
+    # request never disagree. after_save/after_destroy fire inside the
+    # transaction, so this is correct under transactional tests too. The role's
+    # own permission edits don't route through here, but they can't change which
+    # role a subject holds — only the role_permissions, which the memo doesn't
+    # cache (org_role caches the role object, whose grants? reads live).
+    after_save    { CurrentScope::Current.reset_org_role_cache }
+    after_destroy { CurrentScope::Current.reset_org_role_cache }
+  end
+end

data/app/models/current_scope/role_permission.rb

@@ -0,0 +1,9 @@
+module CurrentScope
+  # One granted controller#action for a role. The key mirrors a permission
+  # auto-derived from the host's routes — there is no permissions table.
+  class RolePermission < ApplicationRecord
+    belongs_to :role
+
+    validates :permission_key, presence: true, uniqueness: { scope: :role_id }
+  end
+end

data/app/models/current_scope/scoped_role_assignment.rb

@@ -0,0 +1,98 @@
+module CurrentScope
+  # A role held on ONE specific record: "Editor of Project #7" grants nothing
+  # on Project #8. Never touches the subject's org-wide role — the two are
+  # independent axes.
+  #
+  # Rows survive host resource destruction by design (polymorphic, no
+  # dependent:). Since #65 those orphan grants open nothing (empty list = 403)
+  # but still rendered like live access until labeled (#90).
+  class ScopedRoleAssignment < ApplicationRecord
+    belongs_to :role
+    belongs_to :subject, polymorphic: true
+    belongs_to :resource, polymorphic: true
+
+    validates :role_id, uniqueness: {
+      scope: [ :subject_type, :subject_id, :resource_type, :resource_id ]
+    }
+
+    # #151: a grant must name exactly one record on BOTH sides.
+    include CurrentScope::StorableKeys
+    validates_storable_polymorphic_keys "subject", "resource"
+
+    # Batch-load polymorphic resources for resolvable types only. A global
+    # includes(:resource) NameErrors when any resource_type is stale; this
+    # constantizes per type and skips unresolvable ones so they stay lazy
+    # and orphaned_resource? labels them inert (#90 / PR #104 review).
+    def self.preload_resolvable_resources!(assignments)
+      list = Array(assignments)
+      return list if list.empty?
+
+      list.group_by(&:resource_type).each do |type, rows|
+        next if type.blank?
+
+        # Same canonical resolver the key guard uses: a namespaced, shortened or
+        # custom polymorphic token must not read as missing here while passing
+        # validation there.
+        klass = CurrentScope.polymorphic_class(type, owner: self)
+        next if klass.nil?
+        next unless klass.respond_to?(:where)
+
+        # Look up by the DECLARED primary key, and index on the string form of it.
+        # resource_id is a string column (#151), so a record keyed on an integer
+        # yields 1 while the grant holds "1"; matching them raw silently misses and
+        # labels a live grant inert. `where` casts the strings back to the column's
+        # own type, so the query is still correct on every adapter.
+        key = klass.primary_key
+        unless key.is_a?(String)
+          mark_resources_loaded(rows, {})
+          next
+        end
+
+        # Only ids that are legal keys for THIS model reach the query. A legacy
+        # collapsed value ("7", left by the pre-#151 integer column) sent at a
+        # PostgreSQL uuid column does not come back empty — it RAISES
+        # `invalid input syntax for type uuid`, and the console page an
+        # administrator opens to find these very grants 500s instead of listing
+        # them as inert. Same rule the resolver applies (CurrentScope
+        # .canonical_key?); a dropped id simply stays unloaded, which is exactly
+        # what orphaned_resource? then labels.
+        ids = rows.map(&:resource_id).uniq.select { |id| CurrentScope.canonical_key?(klass, id) }
+
+        # When NOTHING in the group is a legal key, skip the query but still mark
+        # every row loaded-as-nil below. Returning early instead would leave the
+        # associations lazy, so the first orphaned_resource? call would go and do
+        # per-row exactly the load this method exists to do safely and in bulk.
+        records = ids.empty? ? {} : klass.where(key => ids).index_by { |r| r[key].to_s }
+        mark_resources_loaded(rows, records)
+      end
+
+      list
+    end
+
+    # True when the pointed-at resource is gone (deleted row or unresolvable
+    # type). The grant is inert for authorization (#65) but still a console row.
+    # Memoized: views call this plus the label helper once each; a reset-every-
+    # call would re-query the resource twice per row (PR #104 cubic follow-up).
+    def orphaned_resource?
+      return @orphaned_resource if defined?(@orphaned_resource)
+
+      @orphaned_resource =
+        if resource_id.blank?
+          false
+        else
+          current_scope_resolved_record("resource").nil?
+        end
+    rescue NameError, ActiveRecord::RecordNotFound
+      @orphaned_resource = true
+    end
+
+    def self.mark_resources_loaded(rows, records)
+      rows.each do |row|
+        assoc = row.association(:resource)
+        assoc.target = records[row.resource_id.to_s]
+        assoc.loaded!
+      end
+    end
+    private_class_method :mark_resources_loaded
+  end
+end

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

@@ -0,0 +1,41 @@
+<h1>Events</h1>
+<p class="cs-lede">
+  The append-only authorization ledger, newest first. Every string here is
+  host- or visitor-controlled, so it renders escaped.
+</p>
+
+<div class="cs-card cs-card--flush">
+<table class="cs-table">
+  <thead>
+    <tr>
+      <th>When</th><th>Event</th><th>Actor</th><th>Target</th><th>Details</th>
+    </tr>
+  </thead>
+  <tbody>
+    <% @events.each do |event| %>
+      <tr>
+        <td><%= event.created_at.strftime("%Y-%m-%d %H:%M:%S") %></td>
+        <td><%= event.event %></td>
+        <td>
+          <%= current_scope_gid_label(event.actor) %>
+          <% if event.subject != event.actor %>
+            <span class="cs-chip">as <%= current_scope_gid_label(event.subject) %></span>
+          <% end %>
+        </td>
+        <td><%= event.target_label %></td>
+        <td>
+          <% (event.details || {}).each do |key, value| %>
+            <span class="cs-chip"><%= key %>: <%= Array(value).join(", ") %></span>
+          <% end %>
+        </td>
+      </tr>
+    <% end %>
+  </tbody>
+</table>
+</div>
+
+<nav class="cs-pagination" aria-label="Events pagination">
+  <% if @page > 1 %><%= link_to "← Previous", events_path(page: @page - 1) %><% end %>
+  <span>Page <%= @page %></span>
+  <% if @has_next_page %><%= link_to "Next →", events_path(page: @page + 1) %><% end %>
+</nav>