super_auth 0.7.0 → 0.9.0

data/db/migrate_activerecord/20250101000013_add_resource_tree_guard_to_super_auth_resources.rb

@@ -0,0 +1,15 @@
+class AddResourceTreeGuardToSuperAuthResources < ActiveRecord::Migration[7.0]
+  # Mirrors db/migrate/13_add_resource_tree_guard.rb, which says why: a
+  # parent_id cycle silently widens grants, the models and compile! refuse
+  # it, and this trigger refuses it for writes that go around them. Postgres
+  # only; a no-op elsewhere. The SQL lives in SuperAuth::TreeGuard so a host
+  # can install it from its test setup as well: db/schema.rb cannot carry a
+  # trigger, so a test database built from it has none.
+  def up
+    SuperAuth::TreeGuard.install(db: SuperAuth.db)
+  end
+
+  def down
+    SuperAuth::TreeGuard.remove(db: SuperAuth.db)
+  end
+end

data/db/seeds/sample_data.rb

@@ -29,6 +29,7 @@ puts "Clearing existing data..."
 Edge.delete_all
 Group.update_all(parent_id: nil)
 Role.update_all(parent_id: nil)
+Resource.update_all(parent_id: nil)
 User.delete_all
 Group.delete_all
 Role.delete_all

data/lib/generators/super_auth/install/templates/README

@@ -4,11 +4,15 @@ SuperAuth initializer created at config/initializers/super_auth.rb
 
 Next steps:
 
-1. Run migrations to create the database tables:
+1. Copy the engine's migrations into your app and run them:
 
+   rails super_auth:install:migrations
    rails db:migrate
 
-   (the engine adds its ActiveRecord migrations to your app)
+   (the engine does not run its migrations by itself; repeat both after an
+   upgrade that ships a new one, and re-run SuperAuth::RLS.enable for any
+   table under row-level security, since a policy already in the database
+   does not change with the gem — SuperAuth::RLS.stale lists the ones behind)
 
 2. Mount the engine in config/routes.rb, inside your own authentication.
    It serves the graph editor, which has no authentication of its own:

data/lib/generators/super_auth/install/templates/super_auth.rb

@@ -13,8 +13,11 @@ SuperAuth.setup do |config|
   # Default is :none (returns empty results silently).
   # config.missing_user_behavior = :raise
 
-  # Postgres row-level security: enable it per table with
+  # Wrap request work in SuperAuth.as(current_user) { ... } — in an
+  # around_action, and around jobs — so the ByCurrentUser scope has a user.
+  #
+  # Postgres row-level security is optional and off until you ask for it:
   #   rails generate super_auth:rls Model ...
-  # then wrap request work in SuperAuth.as(current_user) { ... } wherever
-  # database-level enforcement should apply.
+  # Once that migration has run, the same SuperAuth.as call also asserts the
+  # identity the policies read, so turning it on costs no application change.
 end

data/lib/generators/super_auth/rls/templates/migration.rb.erb

@@ -2,6 +2,8 @@ class EnableSuperAuthRls < ActiveRecord::Migration[<%= ActiveRecord::Migration.c
   def up
 <% model_names.each do |model| -%>
     SuperAuth::RLS.enable(:<%= model.tableize.tr('/', '_') %>, resource_type: "<%= model.camelize %>")
+    # Tenancy, not capability: a parent grant admits every row whose column holds a granted record's id, so list every type that may touch the row at all and let the ORM decide who writes.
+    #   parent: { column: :organization_id, resource_type: ["Organization::Member"] }
 <% end -%>
     # Roles allowed to bypass the policies (migrations, seeds, admin jobs):
     # SuperAuth::RLS.grant_system(:app_admin)

data/lib/super_auth/active_record/authorization.rb

@@ -8,13 +8,24 @@ class SuperAuth::ActiveRecord::Authorization < ActiveRecord::Base
       from("(#{SuperAuth::Edge.authorizations.sql}) as super_auth_authorizations".squish)
     end
 
-    # Clears and repopulates the authorizations table from the current graph.
+    # Clears and repopulates the authorizations table from the current graph
+    # with one INSERT ... SELECT on this connection, and returns the row
+    # count; see SuperAuth::Authorization.compile!. The guards run before the
+    # delete, so a refused compile leaves the previous rows in place.
     def compile!
       transaction do
+        # Sequel runs on this transaction's connection (sequel-activerecord_connection),
+        # so the JIT switch lands in it; see SuperAuth::Authorization.compile!.
+        SuperAuth.db.run "SET LOCAL jit = off" if SuperAuth.db.database_type == :postgres
+        SuperAuth::Authorization.assert_compilable!
         delete_all
-        from_graph.each { |auth| create!(auth.attributes.except("id")) }
+        connection.execute(
+          SuperAuth.db[:super_auth_authorizations].insert_sql(
+            SuperAuth::Edge::AUTHORIZATION_COLUMNS, SuperAuth::Authorization.compile_source
+          )
+        )
+        count
       end
-      count
     end
   end
 end

data/lib/super_auth/active_record/by_current_user.rb

@@ -19,44 +19,151 @@ module SuperAuth::ActiveRecord::ByCurrentUser
   # "Resource::ResourceRestartPermission" (edges to a SuperAuth::Resource
   # registered with that external_type). If you can't load the object, you
   # can't call the method.
+  #
+  # A parent step admits a row through a column holding another record's id,
+  # the row's tenancy read off the row itself, so a grant on the organization
+  # reaches every claim whose organization_id it is without a node per claim:
+  #
+  #   class Claim < ApplicationRecord
+  #     super_auth parent: { column: :organization_id,
+  #                          resource_type: %w[Organization::Member Organization::Admin] }
+  #   end
+  #
+  # The steps are OR'd, never collapsed into the parent step alone: a
+  # per-record grant admits a row whose parent column is NULL, and a parent
+  # grant admits rows that have no node. A subclass inherits the declared
+  # parents and is still keyed on its own name; re-declaring on the subclass
+  # replaces its parents alone, on the one inherited default scope, since two
+  # default scopes AND together and would deny every row the parent step
+  # admits.
   def self.included(base)
-    base.send(:default_scope, **{all_queries: true}) do
+    # The attributes mark a hierarchy that already carries the scope. A
+    # second include, a subclass re-declaring or a host including the module
+    # twice, would add a second default scope.
+    return if base.respond_to?(:super_auth_reach)
+
+    base.class_attribute :super_auth_reach, instance_writer: false
+    base.class_attribute :super_auth_wildcard, instance_writer: false, default: true
+    base.extend ClassMethods
+    base.send(:default_scope, all_queries: true) do
       if SuperAuth.current_user.blank?
         raise SuperAuth::Error, "SuperAuth.current_user not set" if SuperAuth.missing_user_behavior == :raise
         next none
       end
+      next self if SuperAuth.current_user.respond_to?(:system?) && SuperAuth.current_user.system?
 
-      if SuperAuth.current_user.respond_to?(:system?) && SuperAuth.current_user.system?
-        self
-      else
-        user_where =
-        if SuperAuth.internal_user?(SuperAuth.current_user)
-          { user_id: SuperAuth.current_user.id }
-        else
-          { user_external_id: SuperAuth.current_user.id, user_external_type: SuperAuth.current_user.class.name }
-        end
+      model.super_auth_preflight!
+      held = SuperAuth::ActiveRecord::ByCurrentUser.held_by(SuperAuth.current_user)
+
+      # Type-level authorization (resource_external_id IS NULL) acts as wildcard:
+      # user has access to ALL records of this type (e.g., admin with ADMIN_ACCESS).
+      if model.super_auth_wildcard && held.where(resource_external_type: model.name, resource_external_id: nil).exists?
+        next self
+      end
+
+      # One IN-subquery per step of the reach, OR'd: the row's own id against
+      # the class's own type, then each parent column against its types. No
+      # type handling here: the external id columns are created with the
+      # app's pk type (SuperAuth.external_id_type at install time), so the
+      # comparison is natively typed. all_queries, so an instance's update,
+      # destroy and reload carry the same OR.
+      model.super_auth_effective_reach.map do |column, types|
+        where(column => held.where(resource_external_type: types).where.not(resource_external_id: nil).select(:resource_external_id))
+      end.reduce(:or)
+    end
+  end
+
+  # The compiled rows `user` holds, matched the way compile! wrote them: a
+  # SuperAuth user by user_id, an application user by its id and class name.
+  def self.held_by(user)
+    if SuperAuth.internal_user?(user)
+      SuperAuth::ActiveRecord::Authorization.where(user_id: user.id)
+    else
+      SuperAuth::ActiveRecord::Authorization.where(user_external_id: user.id, user_external_type: user.class.name)
+    end
+  end
+
+  # ActiveRecord already folds the widths of one storage class into one
+  # abstract type (integer and bigint, varchar and char); text joins varchar
+  # here because the database compares those two natively.
+  def self.type_family(column)
+    column.type == :text ? :string : column.type
+  end
 
-        resource_type = self.model.name
-
-        # Type-level authorization (resource_external_id IS NULL) acts as wildcard:
-        # user has access to ALL records of this type (e.g., admin with ADMIN_ACCESS).
-        type_level = SuperAuth::ActiveRecord::Authorization
-          .where(**user_where, resource_external_type: resource_type, resource_external_id: nil)
-
-        if type_level.exists?
-          self
-        else
-          # Per-record authorization: filter to specific records the user can
-          # access. No type handling here: the external id columns are created
-          # with the app's pk type (SuperAuth.external_id_type at install
-          # time), so the comparison is natively typed.
-          where(
-            id: SuperAuth::ActiveRecord::Authorization
-                .where(**user_where, resource_external_type: resource_type)
-                .where.not(resource_external_id: nil)
-                .select(:resource_external_id))
+  module ClassMethods
+    # The reach as this class queries it: the per-record step on its own
+    # name, since a subclass is its own resource type, then the parent steps
+    # it or its nearest declaring ancestor declared. Recomputed rather than
+    # stored because the stored map's :id names the declaring class.
+    def super_auth_effective_reach
+      { id: [name] }.merge(super_auth_parents)
+    end
+
+    # The compiled rows admitting one row for the current user, each tagged
+    # with the step it came through (:type_level, :id or the parent column),
+    # the rows the scope's subqueries match; the compiled table alone no
+    # longer answers who can see a row once a parent column takes part.
+    # Empty when nothing admits it; [{ step: :system }] under the system
+    # user, which bypasses the compiled table. The row is read unscoped,
+    # since the question is usually asked about one the user cannot see.
+    def super_auth_explain(record_or_id)
+      user = SuperAuth.current_user
+      if user.blank?
+        raise SuperAuth::Error, "SuperAuth.current_user not set" if SuperAuth.missing_user_behavior == :raise
+        return []
+      end
+      return [{ step: :system }] if user.respond_to?(:system?) && user.system?
+
+      record = unscoped.find(record_or_id.is_a?(::ActiveRecord::Base) ? record_or_id.id : record_or_id)
+      held = SuperAuth::ActiveRecord::ByCurrentUser.held_by(user)
+      tag = ->(step, rows) { rows.map { |row| { step: step, **row.attributes.symbolize_keys } } }
+
+      rows = []
+      rows.concat tag.(:type_level, held.where(resource_external_type: name, resource_external_id: nil)) if super_auth_wildcard
+      super_auth_effective_reach.each do |column, types|
+        value = record[column]
+        # A NULL column is reached by nothing: "col = NULL" is never true.
+        next if value.nil?
+        rows.concat tag.(column, held.where(resource_external_type: types, resource_external_id: value))
+      end
+      rows
+    end
+
+    # Each parent column must exist on the table and share
+    # resource_external_id's type family. Checked on the first query rather
+    # than at declaration so a process can boot before its migrations run,
+    # and once per model, since the answer changes only with the schema.
+    # Postgres refuses a mismatched comparison; MySQL coerces it silently and
+    # admits whatever rows the cast happens to match, so the declaration is
+    # refused here, naming both sides.
+    def super_auth_preflight!
+      return if @super_auth_preflight
+
+      expected = SuperAuth::ActiveRecord::Authorization.columns_hash.fetch("resource_external_id")
+      super_auth_parents.each_key do |column|
+        actual = columns_hash[column.to_s]
+        unless actual
+          raise SuperAuth::Error, "#{name} declares parent column #{column}, which table #{table_name} does not have"
+        end
+        unless SuperAuth::ActiveRecord::ByCurrentUser.type_family(actual) == SuperAuth::ActiveRecord::ByCurrentUser.type_family(expected)
+          raise SuperAuth::Error, "#{name}.#{column} is #{actual.sql_type} but super_auth_authorizations.resource_external_id is #{expected.sql_type}; " \
+                                  "a parent column must have the type of SuperAuth.external_id_type, the type of the ids it holds"
         end
       end
+      @super_auth_preflight = true
+    end
+
+    # The preflight's answer is column information, so it is dropped with it.
+    def reset_column_information
+      @super_auth_preflight = nil
+      super
+    end
+
+    private
+
+    # No macro call (the module included directly) declares no parents.
+    def super_auth_parents
+      super_auth_reach ? SuperAuth::Reach.parents(super_auth_reach) : {}
     end
   end
 end

data/lib/super_auth/active_record/group.rb

@@ -1,5 +1,8 @@
+require_relative "nested"
+
 class SuperAuth::ActiveRecord::Group < ActiveRecord::Base
   self.table_name = 'super_auth_groups'
+  include SuperAuth::ActiveRecord::Nested
 
   belongs_to :parent, class_name: 'SuperAuth::ActiveRecord::Group', optional: true
 

data/lib/super_auth/active_record/nested.rb

@@ -0,0 +1,43 @@
+# The tree safety SuperAuth::Nestable gives the Sequel models, for the three
+# ActiveRecord twins that nest: a node may not be its own parent nor sit
+# under one of its own descendants (either closes a parent_id cycle, and a
+# cycle silently makes every node in it an ancestor of every other), and
+# destroying a node takes its compiled rows and its edges with it. The
+# ancestor walk runs through the Sequel twin on this connection
+# (sequel-activerecord_connection), so it sees the open transaction. Children
+# of a destroyed node are not touched: the foreign key refuses to orphan
+# them, and re-rooting or deleting them is the caller's decision.
+module SuperAuth::ActiveRecord::Nested
+  def self.included(base)
+    base.validate :parent_outside_own_subtree
+    base.before_destroy :purge_grants
+  end
+
+  private
+
+  # SuperAuth::ActiveRecord::Group -> SuperAuth::Group. Through base_class,
+  # because a host subclasses these models to add scopes and callbacks and
+  # the twin is the gem's: on the concrete name, Module#const_get falls
+  # through to Object and returns the host's own class, which has neither
+  # ancestor_pairs nor singularize, so every re-parent and every destroy
+  # through a subclass raised NoMethodError.
+  def sequel_twin
+    SuperAuth.const_get(self.class.base_class.name.split("::").last)
+  end
+
+  def parent_outside_own_subtree
+    return if parent_id.nil? || !will_save_change_to_attribute?(:parent_id)
+
+    if parent_id == id
+      errors.add(:parent_id, "cannot be the node itself")
+    elsif persisted? && sequel_twin.ancestor_pairs(of: [parent_id]).where(ancestor_id: id).count > 0
+      errors.add(:parent_id, "is inside the node's own subtree, which would close a cycle")
+    end
+  end
+
+  def purge_grants
+    column = :"#{sequel_twin.singularize}_id"
+    SuperAuth::ActiveRecord::Authorization.where(column => id).delete_all
+    SuperAuth::ActiveRecord::Edge.where(column => id).delete_all
+  end
+end

data/lib/super_auth/active_record/resource.rb

@@ -1,6 +1,13 @@
+require_relative "nested"
+
 class SuperAuth::ActiveRecord::Resource < ActiveRecord::Base
   self.table_name = 'super_auth_resources'
+  include SuperAuth::ActiveRecord::Nested
   belongs_to :external, polymorphic: true, optional: true
+  # optional: is load-bearing: Rails hosts set belongs_to_required_by_default,
+  # the gem's own suite does not, so a missing one passes CI and fails the
+  # host on every root node.
+  belongs_to :parent, class_name: 'SuperAuth::ActiveRecord::Resource', optional: true
 
   # `super_auth_label` is a stored snapshot of the application record's human
   # name, so the editor can render "Gulf War presumptive" instead of
@@ -14,6 +21,23 @@ class SuperAuth::ActiveRecord::Resource < ActiveRecord::Base
   # write this row.
   before_save :set_label, if: :external_id?
 
+  # Type-level nodes that admit nobody: their external_type names no loaded
+  # ActiveRecord class that carries the ByCurrentUser scope — the class does
+  # not exist, or the scope sits only on a nested subclass (User with the
+  # scope on User::Directory and User::Writable) — so every row compiled from
+  # them matches no model's query and nothing notices. Hosts accumulate them
+  # by moving a model to the readonly-base-plus-Writable-subclass pattern and
+  # never pruning the type list that mints the nodes; the first consumer found
+  # seven. Rails-side by necessity: only a process with the models loaded can
+  # say what a type string resolves to, which is why this is not a bucket of
+  # SuperAuth::RLS.coverage.
+  def self.dead_type_level_nodes
+    where(external_id: nil).where.not(external_type: nil).reject do |node|
+      klass = node.external_type.safe_constantize
+      klass.is_a?(Class) && klass < ::ActiveRecord::Base && klass.include?(SuperAuth::ActiveRecord::ByCurrentUser)
+    end
+  end
+
   # Re-derive the label after the application record is renamed. Hosts call it
   # from whatever already syncs the node; super_auth:labels:backfill calls it
   # for every row.
@@ -33,10 +57,10 @@ class SuperAuth::ActiveRecord::Resource < ActiveRecord::Base
   # path, and never fails the save. Three things derive nil and none of them
   # means "this record has no name": RLS makes the application record
   # unreadable without an asserted identity, external_type is a plain string
-  # that can name a class this process has not loaded, and type-level rows
-  # (external_id IS NULL) have no record to name at all. Writing nil for any
-  # of them would turn "this label is stale" into data, which is the failure
-  # this column exists to avoid.
+  # that can name a class this process has not loaded, and id-less rows — a
+  # container, or a type-level node — have no record to name at all.
+  # Writing nil for any of them would turn "this label is stale" into data,
+  # which is the failure this column exists to avoid.
   def derived_label
     SuperAuth.label_for(external)
   rescue NameError

data/lib/super_auth/active_record/role.rb

@@ -1,5 +1,8 @@
+require_relative "nested"
+
 class SuperAuth::ActiveRecord::Role < ActiveRecord::Base
   self.table_name = 'super_auth_roles'
+  include SuperAuth::ActiveRecord::Nested
 
   belongs_to :parent, class_name: 'SuperAuth::ActiveRecord::Role', optional: true
 

data/lib/super_auth/active_record.rb

@@ -4,8 +4,36 @@ end
 
 class ActiveRecord::Base
   class << self
-    def super_auth
-      include SuperAuth::ActiveRecord::ByCurrentUser
+    # Filter this model through the ByCurrentUser scope, keyed on the class's
+    # own name. parent: names the columns through which a grant on another
+    # record reaches a row — the row's tenancy, read off the row itself —
+    # each with the types whose rows admit through it: a Hash
+    # {column:, resource_type: String|[String]} or an Array of them, the
+    # shape SuperAuth::Reach normalises and SuperAuth::RLS.enable takes under
+    # the same keyword, so the same arguments produce the same map in both
+    # layers; whether the arguments agree is what RLS.current? checks.
+    # wildcard: false drops the type-level step (a row with
+    # resource_external_id NULL admitting every record of the type), which
+    # is otherwise always emitted. Omitting it keeps whatever the class
+    # already has — the default on a first declaration, the base's value on a
+    # subclass — because a subclass usually re-declares to replace its
+    # parents, and taking the keyword's default there would silently hand
+    # back the type-level step a base opted out of, against a policy built
+    # without it. Say wildcard: true to put it back. Only true and false are
+    # accepted, with the message RLS.enable gives: nil there means "drop the
+    # step" to the scope and "leave it alone" here, and a truthy string keeps
+    # it, so neither may pass silently. The reach is validated here and the
+    # table is not read: the columns are checked on the first query, so a
+    # process can boot before its migrations run. On a subclass the call
+    # replaces the parents for that subclass alone and adds no second scope.
+    def super_auth(parent: nil, wildcard: nil)
+      unless [true, false, nil].include?(wildcard)
+        raise SuperAuth::Error, "wildcard: must be true or false, got #{wildcard.inspect}"
+      end
+      reach = SuperAuth::Reach.normalize(resource_type: name, parent: parent)
+      include SuperAuth::ActiveRecord::ByCurrentUser unless include?(SuperAuth::ActiveRecord::ByCurrentUser)
+      self.super_auth_reach = reach
+      self.super_auth_wildcard = wildcard unless wildcard.nil?
     end
   end
 end

data/lib/super_auth/authorization.rb

@@ -1,14 +1,67 @@
 class SuperAuth::Authorization < Sequel::Model(:super_auth_authorizations)
-  # Clears and repopulates the compiled table from the current graph, inside
-  # one transaction, and returns the row count. Row by row, like
-  # SuperAuth::ActiveRecord::Authorization.compile!; a single INSERT ... SELECT
-  # is a separate change. Runtime enforcement (ByCurrentUser, the RLS policies)
-  # reads only this table, so every edit to the graph is inert until this runs.
-  def self.compile!
-    db.transaction do
-      dataset.delete
-      SuperAuth::Edge.authorizations.each { |row| dataset.insert(row) }
-      dataset.count
+  class << self
+    # Clears and repopulates the compiled table from the current graph, inside
+    # one transaction, and returns the row count. One INSERT ... SELECT of
+    # SuperAuth::Edge.authorizations, like the ActiveRecord twin: row by row
+    # the same graph loaded at ~570 rows/s through the model, which at a
+    # million rows is most of an hour in one held transaction, with every row
+    # resident in Ruby. Runtime enforcement (ByCurrentUser, the RLS policies)
+    # reads only this table, so every edit to the graph is inert until this
+    # runs. The guards run first, before the delete, so a refused compile
+    # leaves the previous rows in place rather than an empty table.
+    #
+    # Postgres JIT-compiles the union's expressions on every run: 539 LLVM
+    # functions, 1.6-2.2s of optimisation and emission for a query that then
+    # executes in milliseconds. SET LOCAL scopes the switch to this
+    # transaction, so nothing leaks to the pooled connection.
+    #
+    # Everything here runs on SuperAuth.db, named, not on this class's own
+    # `db`. A host loads the models at require time, before it has connected
+    # anything, so Sequel binds them to whatever Sequel::Model.db is then — a
+    # mock in a Rails boot — and SuperAuth.db= rebinds them afterwards; the
+    # first consumer's binding of this one class had been left behind for
+    # months and nothing noticed until a branch on `db.database_type` here
+    # skipped the timestamp cast and Postgres refused the INSERT.
+    def compile!
+      SuperAuth.db.transaction do
+        SuperAuth.db.run "SET LOCAL jit = off" if SuperAuth.db.database_type == :postgres
+        assert_compilable!
+        table = SuperAuth.db[:super_auth_authorizations]
+        table.delete
+        table.insert(SuperAuth::Edge::AUTHORIZATION_COLUMNS, compile_source)
+        table.count
+      end
+    end
+
+    # What must hold before the compiled table is touched, in the order the
+    # failures are worst. A parent_id cycle in any tree table first: the
+    # walks terminate on one, so it does not fail a compile — it quietly
+    # makes every node in the cycle an ancestor of every other, and a grant
+    # on any of them reaches all their subtrees. Then the resource tree's own
+    # rule, that type-level nodes are flat.
+    def assert_compilable!
+      SuperAuth::Group.assert_acyclic!
+      SuperAuth::Role.assert_acyclic!
+      SuperAuth::Resource.assert_acyclic!
+      SuperAuth::Resource.assert_compilable!
+    end
+
+    # The SELECT the compile inserts from. The eight timestamp columns travel
+    # through the union as text (the MySQL collation reason in
+    # SuperAuth::Edge.string_cast_type), and Postgres has no assignment cast
+    # from text to timestamp: inserting the bare union there fails with
+    # "column ... is of type timestamp ... but expression is of type text".
+    # They are cast back on Postgres only. MySQL converts on assignment, and
+    # SQLite's CAST(... AS timestamp) has NUMERIC affinity, which would keep
+    # the "2026" of a date and drop the rest.
+    def compile_source
+      graph = SuperAuth::Edge.authorizations
+      return graph unless SuperAuth.db.database_type == :postgres
+
+      columns = SuperAuth::Edge::AUTHORIZATION_COLUMNS.map do |column|
+        column.end_with?("_at") ? Sequel.cast(column, :timestamp).as(column) : column
+      end
+      graph.from_self(alias: :graph).select(*columns)
     end
   end
 end