super_auth 0.4.0 → 0.8.0

data/lib/super_auth/editor/seed.rb

@@ -0,0 +1,176 @@
+require "super_auth"
+
+module SuperAuth
+  class Editor
+    # Sample graph for the editor. "Acme Cloud": three departments that are
+    # deliberately DISJOINT. Engineering, Finance, and Support each have their
+    # own users, roles, permissions, and resources with no shared nodes, so
+    # traversal is obvious: click anyone in Engineering and only Engineering
+    # lights up.
+    #
+    # The hierarchy matches how grants inherit:
+    #   - The shared "Developer" role is attached to the Engineering PARENT
+    #     group, so every engineer (Backend + Frontend) inherits it, while
+    #     Backend and Frontend each also hold a child-group grant the other
+    #     does not.
+    #   - "Support Lead" is the PARENT role of "Support Agent": a lead inherits
+    #     the agent's abilities plus refunds; an agent does not get refunds.
+    #   - "clusters" is a CONTAINER resource holding production_cluster and
+    #     staging_cluster. deploy is granted on the container and reaches both
+    #     clusters through the tree; restart_server and Morgan's direct grant
+    #     name production_cluster alone, so the tree shows a container grant
+    #     and a leaf grant side by side.
+    #
+    # Special people:
+    #   - Riley (Auditor): read-only into BOTH Finance and Support
+    #   - Morgan (Admin): direct user->resource access across departments
+    #   - Nina (New Hire): no access at all
+    #
+    # Destructive: run! replaces the whole graph, including the compiled
+    # authorizations. Only ever runs on request (super_auth-editor --seed).
+    module Seed
+      module_function
+
+      # Returns the row counts per table.
+      def run!
+        SuperAuth.db.transaction do
+          clear!
+
+          grp = SuperAuth::Group
+          rol = SuperAuth::Role
+          usr = SuperAuth::User
+          perm_m = SuperAuth::Permission
+          res_m = SuperAuth::Resource
+          edg = SuperAuth::Edge
+
+          # ===== GROUPS (Engineering is a parent of Backend + Frontend) =====
+          engineering = grp.create(name: "Engineering")
+          backend     = grp.create(name: "Backend",  parent_id: engineering.id)
+          frontend    = grp.create(name: "Frontend", parent_id: engineering.id)
+          finance     = grp.create(name: "Finance")
+          support     = grp.create(name: "Customer Support")
+
+          # ===== ROLES (Support Lead is the parent of Support Agent) =====
+          developer     = rol.create(name: "Developer")
+          sre           = rol.create(name: "SRE")
+          accountant    = rol.create(name: "Accountant")
+          support_lead  = rol.create(name: "Support Lead")
+          support_agent = rol.create(name: "Support Agent", parent_id: support_lead.id)
+
+          # ===== PERMISSIONS (disjoint per department) =====
+          merge_code     = perm_m.create(name: "merge_code")
+          read_repo      = perm_m.create(name: "read_repo")
+          deploy         = perm_m.create(name: "deploy")
+          run_migrations = perm_m.create(name: "run_migrations")   # Backend-only
+          publish_site   = perm_m.create(name: "publish_site")     # Frontend-only
+          restart_server = perm_m.create(name: "restart_server")   # SRE-only
+          view_ledger    = perm_m.create(name: "view_ledger")
+          issue_invoice  = perm_m.create(name: "issue_invoice")
+          run_payroll    = perm_m.create(name: "run_payroll")
+          view_ticket    = perm_m.create(name: "view_ticket")
+          close_ticket   = perm_m.create(name: "close_ticket")
+          issue_refund   = perm_m.create(name: "issue_refund")     # Support Lead-only
+
+          # ===== RESOURCES (disjoint per department) =====
+          source_repo        = res_m.create(name: "source_repo")
+          clusters           = res_m.create(name: "clusters")                                   # container
+          production_cluster = res_m.create(name: "production_cluster", parent_id: clusters.id)
+          res_m.create(name: "staging_cluster", parent_id: clusters.id)  # reached only through clusters
+          app_database       = res_m.create(name: "app_database")      # Backend
+          marketing_site     = res_m.create(name: "marketing_site")    # Frontend
+          general_ledger     = res_m.create(name: "general_ledger")
+          invoices           = res_m.create(name: "invoices")
+          support_tickets    = res_m.create(name: "support_tickets")
+          customer_accounts  = res_m.create(name: "customer_accounts")
+
+          # ===== USERS =====
+          alice  = usr.create(name: "Alice")   # Backend dev
+          bob    = usr.create(name: "Bob")     # Frontend dev
+          sam    = usr.create(name: "Sam")     # SRE
+          carol  = usr.create(name: "Carol")   # Accountant
+          dave   = usr.create(name: "Dave")    # Accountant
+          erin   = usr.create(name: "Erin")    # Support agent
+          frank  = usr.create(name: "Frank")   # Support lead
+          riley  = usr.create(name: "Riley")   # Auditor (cross-department, read-only)
+          morgan = usr.create(name: "Morgan")  # Admin (direct resource access)
+          usr.create(name: "Nina")             # New hire, no access yet
+
+          # ===== ENGINEERING =====
+          edg.create(user_id: alice.id, group_id: backend.id)
+          edg.create(user_id: bob.id,   group_id: frontend.id)
+          # Shared Developer role on the PARENT group: both Alice and Bob inherit it
+          edg.create(group_id: engineering.id, role_id: developer.id)
+          edg.create(role_id: developer.id, permission_id: merge_code.id)
+          edg.create(role_id: developer.id, permission_id: read_repo.id)
+          edg.create(role_id: developer.id, permission_id: deploy.id)
+          edg.create(permission_id: merge_code.id, resource_id: source_repo.id)
+          edg.create(permission_id: read_repo.id,  resource_id: source_repo.id)
+          # One grant on the container reaches both clusters.
+          edg.create(permission_id: deploy.id,     resource_id: clusters.id)
+          # Child-group-specific grants (Alice gets one, Bob the other)
+          edg.create(group_id: backend.id,  permission_id: run_migrations.id)
+          edg.create(permission_id: run_migrations.id, resource_id: app_database.id)
+          edg.create(group_id: frontend.id, permission_id: publish_site.id)
+          edg.create(permission_id: publish_site.id, resource_id: marketing_site.id)
+          # Sam is an SRE via a direct role assignment
+          edg.create(user_id: sam.id, role_id: sre.id)
+          edg.create(role_id: sre.id, permission_id: restart_server.id)
+          edg.create(role_id: sre.id, permission_id: deploy.id)
+          edg.create(permission_id: restart_server.id, resource_id: production_cluster.id)
+
+          # ===== FINANCE =====
+          edg.create(user_id: carol.id, group_id: finance.id)
+          edg.create(user_id: dave.id,  group_id: finance.id)
+          edg.create(group_id: finance.id, role_id: accountant.id)
+          edg.create(role_id: accountant.id, permission_id: view_ledger.id)
+          edg.create(role_id: accountant.id, permission_id: issue_invoice.id)
+          edg.create(role_id: accountant.id, permission_id: run_payroll.id)
+          edg.create(permission_id: view_ledger.id,   resource_id: general_ledger.id)
+          edg.create(permission_id: issue_invoice.id, resource_id: invoices.id)
+          edg.create(permission_id: run_payroll.id,   resource_id: general_ledger.id)
+
+          # ===== SUPPORT (Lead inherits Agent's abilities via the role hierarchy) =====
+          edg.create(user_id: erin.id,  group_id: support.id)
+          edg.create(user_id: frank.id, group_id: support.id)
+          edg.create(user_id: frank.id, role_id: support_lead.id)     # Frank is a lead
+          edg.create(group_id: support.id, role_id: support_agent.id) # everyone is at least an agent
+          edg.create(role_id: support_agent.id, permission_id: view_ticket.id)
+          edg.create(role_id: support_agent.id, permission_id: close_ticket.id)
+          edg.create(role_id: support_lead.id,  permission_id: issue_refund.id)
+          edg.create(permission_id: view_ticket.id,  resource_id: support_tickets.id)
+          edg.create(permission_id: close_ticket.id, resource_id: support_tickets.id)
+          edg.create(permission_id: issue_refund.id, resource_id: customer_accounts.id)
+
+          # ===== CROSS-CUTTERS =====
+          # Riley audits both the ledger and tickets (direct permission grants).
+          edg.create(user_id: riley.id, permission_id: view_ledger.id)
+          edg.create(user_id: riley.id, permission_id: view_ticket.id)
+          # Morgan has direct resource access across departments (simplest path).
+          edg.create(user_id: morgan.id, resource_id: production_cluster.id)
+          edg.create(user_id: morgan.id, resource_id: general_ledger.id)
+          edg.create(user_id: morgan.id, resource_id: support_tickets.id)
+
+          counts
+        end
+      end
+
+      # Empties the graph and the compiled table. Parents are detached first:
+      # MySQL checks the self-referencing key row by row.
+      def clear!
+        SuperAuth::Edge.dataset.delete
+        SuperAuth::Authorization.dataset.delete
+        [SuperAuth::Group, SuperAuth::Role, SuperAuth::Resource].each { |m| m.dataset.update(parent_id: nil) }
+        [SuperAuth::Group, SuperAuth::Role, SuperAuth::User, SuperAuth::Permission, SuperAuth::Resource].each do |m|
+          m.dataset.delete
+        end
+      end
+
+      def counts
+        {
+          groups: SuperAuth::Group.count, roles: SuperAuth::Role.count, users: SuperAuth::User.count,
+          permissions: SuperAuth::Permission.count, resources: SuperAuth::Resource.count, edges: SuperAuth::Edge.count,
+        }
+      end
+    end
+  end
+end

data/lib/super_auth/editor.rb

@@ -0,0 +1,288 @@
+require "json"
+require "super_auth"
+
+module SuperAuth
+  # A small Rack application that edits the authorization graph: five boxes of
+  # records (groups, roles and resources drawn as trees), client-side
+  # traversal, node and edge CRUD, and a Recompile button.
+  # Rails-free; it needs only SuperAuth.db to be connected and the tables to
+  # exist. Mount it as `run SuperAuth::Editor` (Rack) or
+  # `mount SuperAuth::Editor => "/super_auth/editor"` (Rails), or run
+  # `super_auth-editor`, which serves it on loopback.
+  #
+  # It has no authentication of its own. Anyone who can reach it can rewrite
+  # the graph, so the host must put its own authentication in front of the
+  # mount. Two stdlib-only guards remain: writes must be application/json (a
+  # cross-origin browser cannot send that without a CORS preflight, which is
+  # never answered) and cross-site fetches are refused; `hosts:` additionally
+  # rejects any other Host header, the DNS-rebinding defence the executable
+  # turns on for loopback.
+  #
+  # Edits change the graph, not runtime access: ByCurrentUser and the RLS
+  # policies read the compiled super_auth_authorizations table, so the UI
+  # shows its row count and offers POST /api/compile. A compile the models
+  # refuse (SuperAuth::Error, the wildcard guard) comes back as a 422 with
+  # the model's own message, like any other rejected write.
+  class Editor
+    TYPES = {
+      "user" => :User, "group" => :Group, "role" => :Role,
+      "permission" => :Permission, "resource" => :Resource,
+    }.freeze
+    COLUMNS = {
+      "user" => :user_id, "group" => :group_id, "role" => :role_id,
+      "permission" => :permission_id, "resource" => :resource_id,
+    }.freeze
+    NESTED = %w[group role resource].freeze
+    # The pairs the path strategies read (see Edge.authorizations), unordered.
+    # The models also accept group->resource and role->resource rows, but no
+    # strategy reads them, so they would grant nothing.
+    ALLOWED_PAIRS = [
+      %w[user group], %w[user role], %w[user permission], %w[user resource],
+      %w[group role], %w[group permission], %w[role permission], %w[permission resource],
+    ].map(&:sort).freeze
+    EMPTY_EDGE = { user_id: nil, group_id: nil, role_id: nil, permission_id: nil, resource_id: nil }.freeze
+    INDEX_HTML = File.read(File.join(__dir__, "editor", "index.html")).freeze
+    MAX_BODY = 64 * 1024
+    ID = /\A\d+\z/
+    NAME_MAX = 255
+
+    def self.call(env)
+      (@default ||= new).call(env)
+    end
+
+    # hosts: host names (port ignored) this app answers to; nil disables the check.
+    def initialize(hosts: nil)
+      @hosts = hosts && hosts.map { |h| h.to_s.downcase }
+    end
+
+    def call(env)
+      return forbidden("host not allowed") if @hosts && !@hosts.include?(host_of(env))
+
+      begin
+        SuperAuth.load unless defined?(SuperAuth::User)
+      rescue Sequel::DatabaseError
+        return json(503, error: "super_auth tables not found; run the migrations (super_auth-editor --migrate, or your application's)")
+      end
+
+      method = env["REQUEST_METHOD"]
+      path = env["PATH_INFO"].to_s
+      path = "/" if path.empty?
+      if %w[POST DELETE].include?(method) && env["HTTP_SEC_FETCH_SITE"] == "cross-site"
+        return forbidden("cross-site requests are not accepted")
+      end
+
+      route(method, path, env)
+    rescue SuperAuth::Error => e
+      json(422, error: e.message)
+    rescue Sequel::Error
+      json(422, error: "the database rejected the change")
+    end
+
+    private
+
+    def route(method, path, env)
+      if method == "GET" && path == "/"
+        html
+      elsif method == "GET" && path == "/api/graph"
+        json(200, graph)
+      elsif method == "POST" && path == "/api/compile"
+        json(200, count: SuperAuth::Authorization.compile!)
+      elsif method == "POST" && path == "/api/edges"
+        with_body(env) { |body| create_edge(body) }
+      elsif method == "DELETE" && (m = path.match(%r{\A/api/edges/([^/]+)\z}))
+        delete_edge(m[1])
+      elsif method == "POST" && (m = path.match(%r{\A/api/nodes/([^/]+)\z}))
+        with_body(env) { |body| create_node(m[1], body) }
+      elsif method == "DELETE" && (m = path.match(%r{\A/api/nodes/([^/]+)/([^/]+)\z}))
+        delete_node(m[1], m[2])
+      else
+        json(404, error: "not found")
+      end
+    end
+
+    # ---- reads ----
+
+    def graph
+      {
+        groups: nodes(:Group, :parent_id),
+        roles: nodes(:Role, :parent_id),
+        users: nodes(:User, :external_id, :external_type),
+        permissions: nodes(:Permission),
+        resources: nodes(:Resource, :parent_id, :external_id, :external_type, :super_auth_label),
+        edges: SuperAuth::Edge.order(:id).map { |e| edge_json(e) },
+        authorizations_count: SuperAuth::Authorization.count,
+      }
+    end
+
+    def nodes(model, *extra)
+      rows = SuperAuth.const_get(model).order(:name, :id).map do |n|
+        row = { id: n.id, name: n.name }
+        extra.each { |column| row[column] = n[column] }
+        row
+      end
+      extra.include?(:parent_id) ? tree_order(rows) : rows
+    end
+
+    # The nested types render as a flat list that fakes the tree with
+    # indentation, so a child has to arrive immediately after its parent or
+    # it reads as nested under whatever happens to sort above it — which is
+    # the one question an auditor opens this editor to answer. Sorting by the
+    # ancestors' [name, label, id] triples, outermost first, puts every child
+    # under its own parent and leaves siblings alphabetical; the label only
+    # separates same-named siblings, which synced resources are (one "Claim"
+    # per record), and is absent from groups and roles. All three node sets
+    # are small enough to order in Ruby, and the client's depthOf is
+    # unaffected.
+    #
+    # The key is total, so the order stays defined for broken trees: a row
+    # whose parent_id names a missing row sorts as a root, and a parent cycle
+    # stops at the first repeated id rather than walking forever.
+    def tree_order(rows)
+      by_id = rows.each_with_object({}) { |row, index| index[row[:id]] = row }
+      rows.sort_by do |row|
+        path = []
+        seen = {}
+        node = row
+        while node && !seen[node[:id]]
+          seen[node[:id]] = true
+          path.unshift([node[:name].to_s, node[:super_auth_label].to_s, node[:id]])
+          node = by_id[node[:parent_id]]
+        end
+        path
+      end
+    end
+
+    # ---- writes ----
+
+    def create_node(type, body)
+      model = model_for(type) or return json(404, error: "unknown node type")
+      name = body["name"].to_s.strip
+      return json(422, error: "name is required") if name.empty?
+      return json(422, error: "name is too long (#{NAME_MAX} characters max)") if name.length > NAME_MAX
+      return json(422, error: "the name \"system\" is reserved") if type == "user" && name == "system"
+
+      attrs = { name: name }
+      parent = body["parent_id"]
+      unless parent.nil?
+        return json(422, error: "#{type} records cannot have a parent") unless NESTED.include?(type)
+        return json(422, error: "parent_id must be an integer") unless integer_id?(parent)
+        parent_node = model[parent.to_i]
+        return json(422, error: "parent not found") unless parent_node
+        # "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; " \
+                                  "make a container (a resource with no external type) instead")
+        end
+        attrs[:parent_id] = parent.to_i
+      end
+
+      json(201, node_json(model.create(attrs)))
+    end
+
+    def delete_node(type, id)
+      model = model_for(type) or return json(404, error: "unknown node type")
+      record = integer_id?(id) && model[id.to_i]
+      return json(404, error: "not found") unless record
+
+      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.
+        model.where(parent_id: record.id).update(parent_id: nil) if NESTED.include?(type)
+        model.where(id: record.id).delete
+      end
+      json(200, ok: true)
+    end
+
+    def create_edge(body)
+      a_type = body["a_type"].to_s
+      b_type = body["b_type"].to_s
+      return json(422, error: "unknown node type") unless COLUMNS[a_type] && COLUMNS[b_type]
+      return json(422, error: "an edge links two different node types") if a_type == b_type
+      unless ALLOWED_PAIRS.include?([a_type, b_type].sort)
+        return json(422, error: "no path strategy reads #{a_type} -> #{b_type} edges; it would grant nothing")
+      end
+      return json(422, error: "ids must be integers") unless integer_id?(body["a_id"]) && integer_id?(body["b_id"])
+
+      a_id = body["a_id"].to_i
+      b_id = body["b_id"].to_i
+      return json(404, error: "#{a_type} #{a_id} not found") unless model_for(a_type)[a_id]
+      return json(404, error: "#{b_type} #{b_id} not found") unless model_for(b_type)[b_id]
+
+      # The full five-column hash, so a row created here always has exactly two ids.
+      attrs = EMPTY_EDGE.merge(COLUMNS[a_type] => a_id, COLUMNS[b_type] => b_id)
+      if (edge = SuperAuth::Edge.where(attrs).first)
+        json(200, edge_json(edge))
+      else
+        json(201, edge_json(SuperAuth::Edge.create(attrs)))
+      end
+    end
+
+    def delete_edge(id)
+      edge = integer_id?(id) && SuperAuth::Edge[id.to_i]
+      return json(404, error: "not found") unless edge
+
+      edge.delete
+      json(200, ok: true)
+    end
+
+    # ---- helpers ----
+
+    def model_for(type)
+      TYPES[type] && SuperAuth.const_get(TYPES[type])
+    end
+
+    def integer_id?(value)
+      (value.is_a?(Integer) && value >= 0) || (value.is_a?(String) && value.match?(ID))
+    end
+
+    def node_json(record)
+      {
+        id: record.id,
+        name: record.name,
+        parent_id: record.respond_to?(:parent_id) ? record.parent_id : nil,
+        external_id: record.respond_to?(:external_id) ? record.external_id : nil,
+        external_type: record.respond_to?(:external_type) ? record.external_type : nil,
+      }
+    end
+
+    def edge_json(edge)
+      { id: edge.id, user_id: edge.user_id, group_id: edge.group_id, role_id: edge.role_id,
+        permission_id: edge.permission_id, resource_id: edge.resource_id }
+    end
+
+    def with_body(env)
+      media_type = env["CONTENT_TYPE"].to_s.split(";").first.to_s.strip.downcase
+      return json(415, error: "send application/json") unless media_type == "application/json"
+
+      input = env["rack.input"]
+      raw = input ? input.read(MAX_BODY + 1).to_s : ""
+      return json(413, error: "body too large") if raw.bytesize > MAX_BODY
+
+      body = raw.empty? ? nil : JSON.parse(raw)
+      return json(400, error: "body must be a JSON object") unless body.is_a?(Hash)
+
+      yield body
+    rescue JSON::ParserError
+      json(400, error: "body must be a JSON object")
+    end
+
+    def host_of(env)
+      host = env["HTTP_HOST"].to_s.downcase
+      host.start_with?("[") ? host[/\A\[[^\]]*\]/].to_s : host.split(":").first.to_s
+    end
+
+    def json(status, payload)
+      [status, { "content-type" => "application/json; charset=utf-8", "cache-control" => "no-store" }, [JSON.generate(payload)]]
+    end
+
+    def html
+      [200, { "content-type" => "text/html; charset=utf-8", "cache-control" => "no-store", "x-frame-options" => "DENY" }, [INDEX_HTML]]
+    end
+
+    def forbidden(message)
+      json(403, error: message)
+    end
+  end
+end

data/lib/super_auth/nestable.rb

@@ -53,24 +53,37 @@ module SuperAuth::Nestable
     # pairs on equality; matching ids inside the comma-separated path strings
     # with LIKE forced a nested loop no planner could index, and compile time
     # grew roughly cubically with the graph.
+    #
+    # Both pair CTEs recurse with UNION rather than UNION ALL. The pair
+    # relation is finite (at most n² rows), so UNION stops as soon as a step
+    # 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
       table = pluralize
       name = :"#{singularize}_ancestor_pairs"
       anchor = db[table].select(Sequel[:id].as(:descendant_id), Sequel[:id].as(:ancestor_id))
       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])
+      db.from(name).with_recursive(name, anchor, step, args: [:descendant_id, :ancestor_id], union_all: false)
     end
 
     # Every node paired with itself and each of its descendants, as
     # (ancestor_id, descendant_id). Granting a role grants its whole subtree.
-    def descendant_pairs
+    #
+    # `of:` (a dataset or an array of ids) restricts the anchor to those nodes,
+    # so only their subtrees are walked. Groups and roles are few and the
+    # 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.
+    def descendant_pairs(of: nil)
       table = pluralize
       name = :"#{singularize}_descendant_pairs"
       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])
-      db.from(name).with_recursive(name, anchor, step, args: [:ancestor_id, :descendant_id])
+      db.from(name).with_recursive(name, anchor, step, args: [:ancestor_id, :descendant_id], union_all: false)
     end
 
     def cte(id = nil, direction = :desc)

data/lib/super_auth/railtie.rb

@@ -3,8 +3,6 @@ module SuperAuth
     class Engine < Rails::Engine
       isolate_namespace SuperAuth
 
-      config.paths.add 'app/controllers', eager_load: true
-
       # Use ActiveRecord migrations when in a Rails environment
       if defined?(ActiveRecord)
         config.paths['db/migrate'] = 'db/migrate_activerecord'
@@ -18,6 +16,15 @@ module SuperAuth
         load "tasks/super_auth_tasks.rake"
       end
 
+      # Rails 7.1+ keeps one deprecator per library and applies
+      # config.active_support.deprecation / report_deprecations to each of
+      # them in the active_support.deprecation_behavior initializer, which
+      # runs after load_environment_config — so registration has to come
+      # before that, as Rails' own railties do.
+      initializer "super_auth.deprecator", before: :load_environment_config do |app|
+        app.deprecators[:super_auth] = SuperAuth.deprecator if app.respond_to?(:deprecators)
+      end
+
       initializer "super_auth.initialize" do
         if defined?(ActiveRecord) && defined?(ActiveRecord::Base)
           SuperAuth.db

data/lib/super_auth/resource.rb

@@ -1,2 +1,59 @@
 class SuperAuth::Resource < Sequel::Model(:super_auth_resources)
+  # Resources nest like groups and roles: a grant on a node reaches the node
+  # and every node under it (SuperAuth::Edge.join_resource_subtree). No
+  # unrestrict_primary_key, unlike those two: it exists for the ActiveRecord
+  # twins' descendants_dataset, which builds a Sequel model with an id, and
+  # the ActiveRecord Resource deliberately has none — nothing at runtime
+  # walks a resource tree.
+  include SuperAuth::Nestable
+
+  class << self
+    # A node with an external_type and no external_id is a type-level
+    # (wildcard) node: at runtime it means every record of that type, present
+    # and future (the ByCurrentUser type_level branch, the policy's
+    # `resource_external_id IS NULL OR` clause). A node with neither is a
+    # container. Wildcards are deprecated (see warn_deprecated_wildcards) but
+    # still the only way to authorize INSERT under row-level security, so they
+    # stay; what they may not do is join the tree.
+    def wildcards
+      exclude(external_type: nil).where(external_id: nil)
+    end
+
+    # "Wildcard nodes are flat." compile! calls this before touching the
+    # compiled table, so a refused compile leaves the previous rows in place.
+    # A wildcard with a parent would compile to a (type, NULL) row reachable
+    # through every ancestor's grants — one edge to a container silently
+    # granting every record of a type — and a wildcard with children would
+    # make the children unreachable except through a grant that already covers
+    # them; neither is a shape anyone means. One query: the wildcards that
+    # have a parent, or that some node names as its parent.
+    def assert_compilable!
+      parents = dataset.exclude(parent_id: nil).select(:parent_id)
+      nested = wildcards.where(Sequel.|(Sequel.~(parent_id: nil), { id: parents })).select_order_map(:id)
+      return if nested.empty?
+
+      raise SuperAuth::Error, "Wildcard resource nodes must be flat, but wildcard node(s) #{nested.join(', ')} " \
+        "have a parent or children. A resource node with an external_type and no external_id is a wildcard " \
+        "for every record of that type, not a container: nested in the tree it would compile to a row that " \
+        "reaches every record of its type through the tree. Move each to the root with no children, or give " \
+        "it an external_id."
+    end
+
+    # One warning per compile, naming what exists, through SuperAuth.deprecator
+    # so a Rails host's deprecation config (notify, raise, silence) applies.
+    # A no-op when there are none, which is the common case.
+    def warn_deprecated_wildcards
+      rows = wildcards.order(:id).select_map([:id, :name])
+      return if rows.empty?
+
+      listed = rows.first(10).map { |id, name| "#{name} (#{id})" }
+      listed << "..." if rows.size > 10
+      SuperAuth.deprecator.warn(
+        "#{rows.size} type-level (wildcard) resource node#{'s' if rows.size > 1} " \
+        "(external_type set, external_id NULL): #{listed.join(', ')}. Wildcard nodes are deprecated. " \
+        "They still work, and they remain the only way to authorize INSERT under row-level security; " \
+        "the successor is a grant on a parent record. See the CHANGELOG."
+      )
+    end
+  end
 end