super_auth 0.8.0 → 0.9.0

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,5 +1,8 @@
+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
@@ -18,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.
@@ -38,7 +58,7 @@ class SuperAuth::ActiveRecord::Resource < ActiveRecord::Base
   # 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 id-less rows — a
-  # container, or a deprecated wildcard — have no record to name at all.
+  # 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

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,26 +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.
-  # The wildcard guard runs first, before the delete, so a refused compile
-  # leaves the previous rows in place rather than an empty table; the
-  # deprecation notice comes after the commit, for a compile that happened.
-  #
-  # 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.
-  def self.compile!
-    count = db.transaction do
-      db.run "SET LOCAL jit = off" if db.database_type == :postgres
+  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!
-      dataset.delete
-      SuperAuth::Edge.authorizations.each { |row| dataset.insert(row) }
-      dataset.count
     end
-    SuperAuth::Resource.warn_deprecated_wildcards
-    count
+
+    # 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

data/lib/super_auth/edge.rb

@@ -7,6 +7,19 @@ class SuperAuth::Edge < Sequel::Model(:super_auth_edges)
   many_to_one :role
   many_to_one :resource
 
+  # The columns of `authorizations`, in its order. compile! inserts the union
+  # straight into super_auth_authorizations under this list, so it is the
+  # contract between the five SELECTs below and the table: MySQL and Postgres
+  # both need the column list, and the table has columns the union does not
+  # fill (its own timestamps, the ActiveRecord migration's id).
+  AUTHORIZATION_COLUMNS = %i[
+    user_id user_name user_external_id user_external_type user_created_at user_updated_at
+    group_id group_name group_path group_name_path group_parent_id group_created_at group_updated_at
+    role_id role_name role_path role_name_path role_parent_id role_created_at role_updated_at
+    permission_id permission_name permission_created_at permission_updated_at
+    resource_id resource_name resource_external_id resource_external_type
+  ].freeze
+
   class << self
     # The five strategies are UNIONed positionally. A column that is a real
     # text column in one strategy and CAST(NULL AS ...) in another must be cast
@@ -47,7 +60,10 @@ class SuperAuth::Edge < Sequel::Model(:super_auth_edges)
     # per strategy — 27s per strategy on MySQL at 300k resources, 0.025s
     # anchored — so the walk is sized by the grants, not by the table. On a
     # flat graph it is the identity relation and the compiled rows are exactly
-    # what the previous pk join produced.
+    # what the previous pk join produced. The walk never descends from a
+    # type-level node (Resource.descend_from): a granted (type, NULL) node
+    # pairs with itself and nothing beneath it, on every path that reads this
+    # relation, compile! or not.
     def resource_subtrees
       granted = db[:super_auth_edges].exclude(resource_id: nil).select(:resource_id)
       SuperAuth::Resource.descendant_pairs(of: granted)
@@ -63,12 +79,15 @@ class SuperAuth::Edge < Sequel::Model(:super_auth_edges)
       ds.
         join(resource_subtrees.as(:resource_descendants), ancestor_id: resource_id_column).
         join(Sequel[:super_auth_resources], id: Sequel[:resource_descendants][:descendant_id]).
-        # A (type, NULL) row — a wildcard, every record of its type — is only
-        # ever the node the grant named, never one reached through the tree.
-        # Resource.assert_compilable! refuses that shape loudly, but it is a
-        # separate statement from this one: under READ COMMITTED a write that
-        # nests a wildcard can land between the two, and the compiled table
-        # must not widen a container grant to a whole type because of it.
+        # A (type, NULL) row — a type-level node, every record of its type —
+        # is only ever the node the grant named, never one reached through
+        # the tree; the walk itself refuses the other direction, a node
+        # reached through a type-level parent. Resource.assert_compilable!
+        # refuses both shapes loudly, but it is a separate statement from this
+        # one: under READ COMMITTED a write that nests a type-level node can
+        # land between the two, and the compiled table must not widen a
+        # container grant to a whole type, or a type-level grant to the nodes
+        # under it, because of it.
         where(
           Sequel.|(
             { Sequel[:resource_descendants][:ancestor_id] => Sequel[:resource_descendants][:descendant_id] },

data/lib/super_auth/editor/index.html

@@ -251,12 +251,11 @@ function render(){
       // The external record occupies one slot: its label when the graph
       // stored one, otherwise the Type#id that used to be the only
       // rendering. Either way the other half is the tooltip. A type with no
-      // id is the deprecated type-level (wildcard) node — every record of
-      // the type — and its tooltip says so, since Type#* alone reads as a
-      // typo.
+      // id is the type-level (wildcard) node — every record of the type —
+      // and its tooltip says so, since Type#* alone reads as a typo.
       const wildcard = type === "resource" && !!n.external_type && n.external_id == null;
       const ref = n.external_type ? `${escapeHtml(n.external_type)}#${escapeHtml(n.external_id ?? "*")}` : "";
-      const kind = wildcard ? "type-level (deprecated)" : "external record";
+      const kind = wildcard ? "type-level grant" : "external record";
       const ext = !ref ? "" : (n.super_auth_label
         ? `<span class="ext" title="${wildcard ? `${ref} · ${kind}` : ref}">${escapeHtml(n.super_auth_label)}</span>`
         : `<span class="ext" title="${kind}">${ref}</span>`);

data/lib/super_auth/editor.rb

@@ -171,7 +171,7 @@ module SuperAuth
         # "Wildcard nodes are flat": compile! refuses a tree with a type-level
         # node in it, so refuse the shape at the door with the reason instead.
         if type == "resource" && parent_node.external_type && parent_node.external_id.nil?
-          return json(422, error: "type-level (wildcard) resources are deprecated and cannot contain other resources; " \
+          return json(422, error: "type-level (wildcard) resources are flat and cannot contain other resources; " \
                                   "make a container (a resource with no external type) instead")
         end
         attrs[:parent_id] = parent.to_i
@@ -187,8 +187,17 @@ module SuperAuth
 
       SuperAuth.db.transaction do
         SuperAuth::Edge.where(COLUMNS[type] => record.id).delete
-        # Children become roots: the deny-safe choice, and required before the
-        # delete on MySQL, which checks the self-referencing key row by row.
+        # The node's own compiled rows go with it: runtime reads only that
+        # table, and a row naming a node that no longer exists would keep
+        # granting until the next compile. Rows compiled through it for its
+        # descendants stay until one runs, as after any other revocation.
+        SuperAuth::Authorization.where(COLUMNS[type] => record.id).delete
+        # Children become roots, deliberately, and the client's confirm says
+        # so: not the grandparent's children, whose grants would then reach
+        # them, and not deleted with the node, which is not what "delete this
+        # container" asks. A root grants nothing by itself, so it is the
+        # deny-safe choice. Also required before the delete on MySQL, which
+        # checks the self-referencing key row by row.
         model.where(parent_id: record.id).update(parent_id: nil) if NESTED.include?(type)
         model.where(id: record.id).delete
       end

data/lib/super_auth/nestable.rb

@@ -24,6 +24,44 @@ module SuperAuth::Nestable
     end
   end
 
+  # A node may not be its own parent, nor sit under one of its own
+  # descendants: either closes a parent_id cycle. The pair CTEs terminate on
+  # one (UNION), so a cycle does not hang a compile; it does something
+  # quieter and worse. Every node in a cycle is an ancestor of every other,
+  # so a grant on any of them reaches all of their subtrees — a container
+  # pointed at one of its own children turned a single per-record read into
+  # the container's whole membership, with nothing raised anywhere. Checked
+  # only when parent_id changes, by walking UP from the new parent: that is
+  # one row per level however large the subtree, and unlike the descendant
+  # walk it does not stop at a type-level node
+  # (SuperAuth::Resource.descend_from), so a cycle through one is caught too.
+  # assert_acyclic! covers writes that bypass the model.
+  def validate
+    super
+    return if parent_id.nil? || !changed_columns.include?(:parent_id)
+
+    if parent_id == id
+      errors.add(:parent_id, "cannot be the node itself")
+    elsif !new? && model.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
+
+  # A deleted node takes its compiled rows and its edges with it, in the
+  # transaction that deletes the row: runtime reads only the compiled table,
+  # and a row naming a node that no longer exists would keep granting until
+  # the next compile. Children are not touched. The foreign key refuses to
+  # orphan them, and whether they are re-rooted or deleted is the caller's
+  # decision (the editor re-roots them, deliberately). Rows compiled through
+  # this node for its descendants stay until the next compile, as after any
+  # other revocation.
+  def before_destroy
+    super
+    column = :"#{model.singularize}_id"
+    SuperAuth::Authorization.where(column => id).delete
+    SuperAuth::Edge.where(column => id).delete
+  end
+
   module ClassMethods
     # Helper method to get the appropriate string cast type for the database
     def string_cast_type
@@ -59,10 +97,14 @@ module SuperAuth::Nestable
     # produces nothing new, which on a parent_id cycle is the first time round;
     # UNION ALL re-derives the same pairs forever and compile! never returns.
     # On a valid tree no step repeats a pair, so the output is the same.
-    def ancestor_pairs
+    #
+    # `of:` (a dataset or an array of ids) restricts the anchor to those
+    # nodes, so only their ancestor chains are walked: one row per level.
+    def ancestor_pairs(of: nil)
       table = pluralize
       name = :"#{singularize}_ancestor_pairs"
       anchor = db[table].select(Sequel[:id].as(:descendant_id), Sequel[:id].as(:ancestor_id))
+      anchor = anchor.where(id: of) unless of.nil?
       step = db[name].join(table, id: :ancestor_id).exclude(Sequel[table][:parent_id] => nil).
         select(Sequel[name][:descendant_id], Sequel[table][:parent_id])
       db.from(name).with_recursive(name, anchor, step, args: [:descendant_id, :ancestor_id], union_all: false)
@@ -76,16 +118,62 @@ module SuperAuth::Nestable
     # whole table is cheap; resources are one row per protected record, and an
     # unanchored CTE materialises every pair of the whole table once per
     # strategy that joins it.
+    #
+    # The recursive step joins the parent row only when the model puts a
+    # condition on it (descend_from); the pair CTE itself never carries more
+    # than the two ids.
     def descendant_pairs(of: nil)
       table = pluralize
       name = :"#{singularize}_descendant_pairs"
+      parent = :"#{singularize}_parent"
       anchor = db[table].select(Sequel[:id].as(:ancestor_id), Sequel[:id].as(:descendant_id))
       anchor = anchor.where(id: of) unless of.nil?
       step = db[name].join(table, parent_id: :descendant_id).
         select(Sequel[name][:ancestor_id], Sequel[table][:id])
+      if (condition = descend_from(parent))
+        step = step.join(Sequel[table].as(parent), id: Sequel[name][:descendant_id]).where(condition)
+      end
       db.from(name).with_recursive(name, anchor, step, args: [:ancestor_id, :descendant_id], union_all: false)
     end
 
+    # Whether descendant_pairs continues below a node: a Sequel condition on
+    # the parent row, addressed through the alias `parent`, or nil to descend
+    # from every node. Groups and roles descend from everything.
+    # SuperAuth::Resource stops at a type-level node, so a grant on one yields
+    # its own row and nothing beneath it on every path that reads the walk.
+    def descend_from(parent)
+      nil
+    end
+
+    # Every node some root reaches, walking parent_id downward from the rows
+    # that have none. On a valid forest that is the whole table; what it
+    # misses is exactly the nodes on or under a parent_id cycle (and, where
+    # no foreign key stands, a node whose parent is missing). No path
+    # columns, unlike trees: this runs over the whole resources table before
+    # every compile, and needs only the ids.
+    def rooted
+      table = pluralize
+      name = :"rooted_#{table}"
+      anchor = db[table].where(parent_id: nil).select(:id)
+      step = db[name].join(table, parent_id: :id).select(Sequel[table][:id])
+      db.from(name).with_recursive(name, anchor, step, args: [:id], union_all: false)
+    end
+
+    # Refuses a table with a parent_id cycle in it, naming the nodes no root
+    # reaches. compile! calls this for groups, roles and resources before
+    # touching the compiled table, because a cycle does not fail a compile:
+    # the walks terminate, and every node in the cycle is an ancestor of
+    # every other, so a grant on any of them silently reaches all of their
+    # subtrees. validate refuses the shape at the model; this catches it
+    # after a write that went around the model.
+    def assert_acyclic!
+      unreachable = dataset.exclude(id: rooted).select_order_map(:id)
+      return if unreachable.empty?
+
+      raise SuperAuth::Error, "#{pluralize} has a parent_id cycle: node(s) #{unreachable.join(', ')} " \
+        "cannot be reached from any root. Point one of them at a root, or at no parent, and recompile."
+    end
+
     def cte(id = nil, direction = :desc)
       model = self
       cte_name = model.cte_name