super_auth 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce52cd6a9867c21405fe203e87a765372b5b0febd49109286711c7e546c5118a
-  data.tar.gz: 1b67868c607adfa20b6832eb08e7bbf5ecaabe468a92a7ca4a8e408a8f3f2316
+  metadata.gz: 0f41f8bbae64f5e5ddf3666026d00a64cbe4007037b2c859152b7b3c2e331023
+  data.tar.gz: 6e8b002d7a9e23787565e85494c23b1a1f912770ad800b7a1986a23188701d6e
 SHA512:
-  metadata.gz: '0582f16e103f0a1a00e7ac77edc49a3ba35f59cd0d0c98f4a98f1529c6452ca2adad7f1543df9251e923a8c805a0bce04a95c3fe17d8be86b02063b7b578b1a4'
-  data.tar.gz: f28dedeb421ee5ea689914429e5dac616f8f3a5efa99272b2e4aea2c715c5c880670936483bcb4cfe8f7e5344cff9c72a917296d6cbdb2a2d92213067a09ac29
+  metadata.gz: bde433eba068b2b55edad37701dac014340a5e840e26322238760d554f1e44e8aabc31d934ed776207f02439563ffb52083195cbf99207807ac8e0b23dbf7b5a
+  data.tar.gz: eb3456e6855c070931b5488fd8632eb60d74305753ea007d346f47a11f257aec2104d83061dafdea09f43ab7e90cddfaf4aaf69be236010f2f0896a3821242b0

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 ## [Unreleased]
 
+## [0.8.0] - 2026-09-09
+
+### Added
+
+- `super_auth_resources.parent_id`, a nullable self-referencing key, so resource nodes nest the way groups and roles do. `SuperAuth::Resource` includes `SuperAuth::Nestable` and gains the same tree API: `parent`, `children`, `ancestors`, `descendants` (and the `_dataset` variants), `roots`, `trees`, `ancestor_pairs` and `descendant_pairs`. A node with neither `external_type` nor `external_id` is a container: one per folder, project, tenant or whatever the application nests records under, with the records registered beneath it. Migration 11 in both `db/migrate/` and `db/migrate_activerecord/`.
+- A grant on a resource node reaches the node and every node under it, through all five path strategies. The last hop of each strategy is a join through `SuperAuth::Resource.descendant_pairs` where it was a primary-key join, so the subtree is expanded at compile time and `super_auth_authorizations` gains no columns: `ByCurrentUser` and the row-level security policy are untouched, still read only `resource_external_type` and `resource_external_id` from the compiled table, and cannot tell a row compiled through a container from one granted directly. No recompile is needed after upgrading. On a flat graph the pairs relation is the identity and the compiled rows are exactly what 0.7.0 produced.
+- The pairs CTE is anchored on the resource ids that appear in `super_auth_edges.resource_id` (`descendant_pairs(of:)`, wrapped by `SuperAuth::Edge.resource_subtrees`), so the walk is sized by the grants rather than by the table. 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. Measured at 300,000 resources: MySQL 8 went from 27 s per strategy unanchored to 0.025 s anchored, Postgres from 0.3–0.6 s to 0.008 s.
+- No `resource_path` or `resource_name_path` columns, a deliberate asymmetry with groups and roles. A row compiled through a container carries the descendant node's own `resource_id`, `resource_name`, `resource_external_type` and `resource_external_id` — the record the grant reaches, which is all runtime reads. "Granted through which container" is answered by the graph (`parent_id`, `parent`, `children`) and by the editor, not by the compiled table; the trade is that an audit of the compiled table alone no longer sees the container an edge was drawn to.
+- Containment is not inheritance. Because the compiled row copies the descendant's own `external_type`, the permission-gated subclass rule holds — a `"Post"` grant still says nothing about `"Post::PostPublishPermission"` — but a capability node registered *under* its base-class node is a descendant of it and receives every grant on the base. Register capability nodes as siblings of their base-class nodes, or in a container beside them, never as their children. A documentation rule, not a check: the gem cannot tell a capability subclass from any other type name.
+- The editor renders resources as a tree, creates containers (a resource node with no external link, at the root or under a chosen parent), and refuses two things with a 422 and the reason: creating a node under a wildcard parent, and a compile refused by the guard below (in 0.7.0 a resource create with any `parent_id` was refused as "resource records cannot have a parent"; that message no longer occurs for resources). Application code registers records under a container by saving a node with `parent_id`; there is no re-parent route yet.
+- `SuperAuth.deprecator`, where the gem's deprecation warnings go. An `ActiveSupport::Deprecation` when ActiveSupport is loaded, which the railtie registers as `app.deprecators[:super_auth]` so `config.active_support.deprecation` and `report_deprecations` apply on Rails 7.1+; otherwise a stand-in with the same `warn` and `silenced=`.
+
+### Removed
+
+- The editor's second Users box. The bottom row drew Resources beside a duplicate of the Users box from the top row — same rows, shared selection — with nothing saying why; Resources now spans the bottom row and users are listed once.
+
+### Deprecated
+
+- Type-level (wildcard) resource nodes: a node with an `external_type` and no `external_id`, which at runtime means every record of that type, present and future (`ByCurrentUser`'s type-level branch; the policy's `resource_external_id IS NULL OR` clause). They keep working, unchanged, and no removal version is promised. What changes is at compile time. `compile!` (both twins) now warns once per compile through `SuperAuth.deprecator`, naming up to ten of them, and refuses a wildcard that has a parent or children, raising `SuperAuth::Error` ("Wildcard resource nodes must be flat, but wildcard node(s) 12, 15 have a parent or children. …") before the compiled table is touched, so the previous rows stay. That is the one shape the tree cannot hold: nested under a container, a wildcard 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 nodes under a wildcard are unreachable except through a grant that already covers them. The rule is that wildcard nodes are flat: at the root, with no children, or given an `external_id`. The guard and the compile are two statements, so the subtree join carries the same rule as a predicate: a `(type, NULL)` row is only ever the node a grant named, never one reached through a parent, whatever a concurrent write commits between the two under `READ COMMITTED`. The guard is the loud error; the predicate is the guarantee.
+- A container is not a replacement for a wildcard on a table under row-level security, and the wildcard remains the only way to authorize INSERT there this release. The policy is `FOR ALL` with no `WITH CHECK`, so Postgres reuses `USING` for new rows, and a per-record row can only match an id the application has already registered and compiled. Moving an RLS-protected type from a wildcard to a container loses INSERT, needs a resource node saved and a full recompile for every new record before it is visible, and needs a role that can write the gem's tables, which `enable` grants `SELECT` on only. The successor is a grant on a parent record — `SuperAuth::RLS.enable(:documents, resource_type: "Document", parent: { column: :folder_id, resource_type: "Folder" })`, with the policy matching per record on `t.id` or per record on the parent column, and a `ByCurrentUser` mirror — planned for the next release, which is when the wildcard stops being needed. Until then a wildcard on an RLS host is the supported shape and the warning is a notice, not a fault.
+
+### Fixed
+
+- `compile!` turns Postgres JIT off for its own transaction (`SET LOCAL jit = off`). Postgres was JIT-compiling the five-strategy union's expressions on every compile — 358 LLVM functions in 0.7.0, 539 with the new subtree joins — spending 1.6 s (0.7.0) to 2.2 s (0.8.0) in LLVM optimisation and emission for a query that executes in about 10 ms; the whole of the "compile is slow on Postgres" cost was JIT, on any graph size. `SET LOCAL` dies with the transaction, so nothing reaches the pooled connection. `SuperAuth::Edge.authorizations` called on its own is unchanged.
+- `compile!` no longer runs forever on a `parent_id` cycle. The two pair CTEs in `SuperAuth::Nestable` (`ancestor_pairs`, `descendant_pairs`) recurse with `UNION` instead of `UNION ALL`: the pair relation is finite, so `UNION` stops the first time a step produces nothing new, which on a cycle is the first time round, where `UNION ALL` re-derived the same pairs without end. MySQL aborted after 1001 iterations (`cte_max_recursion_depth`); Postgres and SQLite looped until killed. Output is unchanged on a valid tree, where no step repeats a pair. The path-building tree CTEs the strategies join for group and role path columns are anchored on the roots and walk downward, so they never enter a cycle: a cyclic group or role component is unreachable from any root and every grant that passes through it compiles to no rows, silently, fail-closed. A check against cycles at write time remains open.
+
+### Upgrade notes
+
+- Run migration 11 before deploying code that saves resource nodes or compiles: `SuperAuth::Resource` now reads `parent_id`, so `compile!` on an un-migrated schema fails with a missing-column error. In Rails, `rails railties:install:migrations` (or the app's equivalent) copies the new migration into the app and `rails db:migrate` runs it — the engine points the install task at `db/migrate_activerecord` but does not run its migrations on its own, which the install generator's notes used to claim and now do not. Without Rails, `SuperAuth.install_migrations` or `super_auth-editor --migrate`; `rake super_auth:migrate` exists only inside a Rails app (its tasks depend on `:environment`).
+- No recompile: the compiled table has the same columns and, on a flat graph, the same rows.
+- With wildcard nodes in the graph, every compile prints one deprecation line naming them. Silence it with the Rails deprecation config — the deprecator is `app.deprecators[:super_auth]`, so `config.active_support.deprecation = :silence` and `config.active_support.report_deprecations = false` both apply — or with `SuperAuth.deprecator.silenced = true`.
+- Compiled-table growth: a grant on a container compiles one row per descendant per path, and `compile!` inserts row by row, so a container over many records lengthens every compile in proportion. A single `INSERT ... SELECT` is the tracked follow-up.
+
 ## [0.7.0] - 2026-09-07
 
 ### Fixed

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    super_auth (0.7.0)
+    super_auth (0.8.0)
       sequel
 
 GEM

data/README.md

@@ -16,8 +16,8 @@ SuperAuth enforces authorization in the database, so any language can participat
 
 ## Supported databases
 
-PostgreSQL 13+, MySQL 8.0+, and SQLite 3.44+. The group and role trees are recursive
-CTEs and the path columns use `concat()`, which sets those floors. CI runs the full
+PostgreSQL 13+, MySQL 8.0+, and SQLite 3.44+. The group, role and resource trees are
+recursive CTEs and the path columns use `concat()`, which sets those floors. CI runs the full
 suite against each of the three. Row-level security is Postgres only.
 
 ## Docs
@@ -28,9 +28,13 @@ How `super_auth` stacks up against other authentication strategies:
 ## Graph editor
 
 A Rails-free editor for the authorization graph: five boxes (groups, roles, users,
-permissions, resources); click any record to trace what it can reach and what reaches
-it; connect two records to draw an edge; delete records and edges; recompile. It ships
-in the gem as a Rack app and a command.
+permissions, resources), of which groups, roles and resources are drawn as trees; click
+any record to trace what it can reach and what reaches it; connect two records to draw
+an edge; create records, including a resource container under a chosen parent; delete
+records and edges; recompile. The editor makes containers, not application records:
+your code registers a record under a container by saving a resource node with
+`parent_id`, and a grant on the container reaches everything under it. It ships in the
+gem as a Rack app and a command.
 
 ```bash
 gem install super_auth rackup webrick        # any Rack server works; puma too
@@ -216,7 +220,8 @@ identity in the current transaction and nothing else, and `SuperAuth::RLS.instal
 reports whether `enable` has run, so no application needs to know the SQL functions'
 signatures. Non-Ruby apps use the SQL contract directly. Each policy checks `super_auth_authorizations` with the same
 semantics as `ByCurrentUser`: type-level authorizations (`resource_external_id IS NULL`)
-act as a wildcard, per-record authorizations match on id. Any object with an `id`
+act as a wildcard (deprecated, see CHANGELOG 0.8.0), per-record authorizations match
+on id. Any object with an `id`
 works as the user, including SuperAuth's own user records. For a user whose `system?`
 is true, `SuperAuth.as` calls `super_auth_system()` instead, so the connection's role
 must have been given the bypass with `SuperAuth::RLS.grant_system`.
@@ -228,7 +233,11 @@ must have been given the bypass with `SuperAuth::RLS.grant_system`.
   reach protected rows.
 - Creating rows requires a type-level authorization for that resource type (or system
   context): the policy is `FOR ALL` with no `WITH CHECK`, so Postgres reuses its
-  `USING` expression as the implicit `WITH CHECK` for INSERTs and UPDATEs.
+  `USING` expression as the implicit `WITH CHECK` for INSERTs and UPDATEs. Type-level
+  nodes are deprecated (see CHANGELOG 0.8.0) but remain the only way to authorize
+  INSERT here until the parent-record grant planned for the next release; a resource
+  container does not replace one on a protected table, because a per-record row can
+  only match an id that already exists.
 - The transaction stamp calls `pg_current_xact_id()`, which assigns a real transaction
   id even to read-only transactions — one extra xid per protected transaction.
   Negligible for almost everyone; revisit with a virtual-xid variant only if
@@ -273,16 +282,16 @@ The basis for how this works is that the rules engine is trying to match a user
 The engine determines if it can find an authorization route betewen a user and a resource. It does so by looking at users, groups, roles, permissions.
 
                           +---+           +---+
-                          |   |           |   |      (Group nests within Group,
-                          |   v           |   v       Role nests within Role)
+                          |   |           |   |      (Group, Role and Resource
+                          |   v           |   v       each nest within themselves)
                          +-------+       +------+
                          | Group |<----->| Role |
                          +-------+\    / +------+
                              ^     \  /     ^
                              |      \/      |
-                             |      /\      |
-                             |     /  \     |
-                             V    /    \    V
+                             |      /\      |               +---+
+                             |     /  \     |               |   |
+                             V    /    \    V               |   v
     +---------------+    +------+/      \+------------+    +----------+      +-------------------+
     | YourApp::User |<-->| User |<------>| Permission |<-->| Resource | <--> | YourApp::Resource |
     +---------------+    +------+        +------------+    +----------+      +-------------------+
@@ -292,9 +301,10 @@ The engine determines if it can find an authorization route betewen a user and a
 
 
 The lines between the boxes are called [edges](https://en.wikipedia.org/wiki/Glossary_of_graph_theory#edge).
-The self-loops on `Group` and `Role` mean each nests within itself: a `Group` can contain
-child `Group`s and a `Role` can contain child `Role`s, recursively. Grants on a parent
-flow to every descendant — which is why `Group` and `Role` are described as *trees*.
+The self-loops on `Group`, `Role` and `Resource` mean each nests within itself: a `Group`
+can contain child `Group`s, a `Role` child `Role`s, and a `Resource` child `Resource`s (a
+container with your records registered under it), recursively. Grants on a parent flow to
+every descendant — which is why `Group`, `Role` and `Resource` are described as *trees*.
 
 In general the super_auth has 5 different pathing strategies to search for access.
 
@@ -305,7 +315,7 @@ In general the super_auth has 5 different pathing strategies to search for acces
     5. users <->                                         resource
 
 Edges can be drawn between any 2 objects, allowing super_auth can seamlessly scale in complexity with you.
-When `Group` and `Role` are used, the rules will apply to all descedants. If there are any edges
+When `Group`, `Role` and `Resource` nodes are nested, the rules apply to all descendants. If there are any edges
 between the specified user and the resource, then access is granted.
 
 
@@ -430,13 +440,18 @@ class Resource < ApplicationRecord
 end
 ```
 
-Approve access to the subclass the same way as any other resource — register it by its class name and draw edges to it:
+Approve access to the subclass the same way as any other resource — register it by its class name and draw edges to it. Here the nodes sit in a container, so one edge covers every server registered under it:
 
 ```ruby
-restartable = SuperAuth::Resource.create(
-  name: "restartable servers",
-  external_type: "Resource::ResourceRestartPermission"
-)
+restartable = SuperAuth::Resource.create(name: "restartable servers")   # a container
+servers.each do |server|
+  SuperAuth::Resource.create(
+    name: server.name,
+    external_type: "Resource::ResourceRestartPermission",
+    external_id: server.id,
+    parent: restartable
+  )
+end
 restart = SuperAuth::Permission.create(name: "restart")
 SuperAuth::Edge.create(user: sa_user, permission: restart)
 SuperAuth::Edge.create(permission: restart, resource: restartable)
@@ -448,6 +463,8 @@ Resource::ResourceRestartPermission.find(id) # needs its own explicit approval
 
 Grants are per class in both directions: a `"Resource"` grant does not unlock the subclass, and a `"Resource::ResourceRestartPermission"` grant does not unlock the base class.
 
+The resource tree is containment, not inheritance. A row compiled through a container copies the descendant node's own `external_type`, so nesting does not weaken the rule above; what weakens it is the node's position. A `"Resource::ResourceRestartPermission"` node whose parent is the `"Resource"` node is a descendant of it and receives every grant drawn on `"Resource"`. Register capability nodes as siblings of their base-class nodes, or in a container beside them as above, never as their children.
+
 ## Row-Level Security for permission-gated models
 
 For defense in depth on Postgres (13+), enable a policy on the table. It is keyed by a single resource type — the base class's name — and enforces *row visibility* using the same [contract described above](#postgres-row-level-security-optional):
@@ -465,7 +482,7 @@ end
 # outside the block there is no asserted identity, so the policy matches nothing
 ```
 
-Works with `SuperAuth::User` records (matched by `user_id`) or your own user objects (matched by `user_external_id` / `user_external_type`); type-level wildcard grants (`resource_external_id IS NULL`) and the system user behave exactly as they do in the ActiveRecord scope. `SuperAuth::RLS.disable(:resources)` removes the policy.
+Works with `SuperAuth::User` records (matched by `user_id`) or your own user objects (matched by `user_external_id` / `user_external_type`); type-level wildcard grants (`resource_external_id IS NULL`, deprecated — see CHANGELOG 0.8.0) and the system user behave exactly as they do in the ActiveRecord scope. `SuperAuth::RLS.disable(:resources)` removes the policy.
 
 Because a policy sees only the table, not which Ruby class issued the query, row-level security enforces access to the **base** resource type: a `"Resource"` grant makes the row visible in the database, but the policy cannot distinguish the `"Resource::ResourceRestartPermission"` subclass. Per-class (capability) enforcement therefore stays with the ORM scope — the database is the row-visibility backstop, the client gates the capability.
 

data/USAGE.md

@@ -62,7 +62,7 @@ rails railties:install:migrations
 rails db:migrate
 ```
 
-This creates the `super_auth_*` tables (users, groups, roles, permissions, resources, edges, authorizations) alongside your application's tables.
+This creates the `super_auth_*` tables (users, groups, roles, permissions, resources, edges, authorizations) alongside your application's tables. The engine does not run its migrations by itself, so repeat both commands after upgrading to a version that ships a new one (0.8.0 adds migration 11, `parent_id` on resources).
 
 **Step 4.** Set the current user in your controller:
 
@@ -134,7 +134,7 @@ SuperAuth models authorization as a graph with 5 entity types:
 | **Group**      | Organizational units (teams, departments, etc) | Yes (nested)  |
 | **Role**       | Job titles or permission sets                  | Yes (nested)  |
 | **Permission** | Actions (read, write, deploy, etc)             | No            |
-| **Resource**   | Things being protected (files, APIs, records)  | No            |
+| **Resource**   | Things being protected (files, APIs, records)  | Yes (nested)  |
 
 **Edges** are connections drawn between any two entities. SuperAuth traverses the graph to find all valid paths from a User to a Resource. If a path exists, access is granted.
 
@@ -245,22 +245,77 @@ write_perm  = SuperAuth::Permission.create(name: "write")
 deploy_perm = SuperAuth::Permission.create(name: "deploy")
 ```
 
-### Resources
+### Resources (hierarchical)
 
-Resources represent what you are protecting. They can link to your app's models.
+Resources represent what you are protecting. A node with neither `external_type` nor `external_id` is a container; a node with both points at one record of your application. Resources nest like groups and roles, and a grant on a node reaches the node and every node under it, so the usual shape is a container per folder, project, tenant or whatever your application nests records under, with the records registered beneath it.
 
 ```ruby
-# Named resource
+# A named resource with nothing behind it
 staging = SuperAuth::Resource.create(name: "staging")
 
-# Linked to an ActiveRecord model
-posts = SuperAuth::Resource.create(
-  name: "posts",
-  external_id: nil,
-  external_type: "Post"
+# A container, and a record of your app registered under it
+reports = SuperAuth::Resource.create(name: "reports")
+q3 = SuperAuth::Resource.create(
+  name: "Q3 report",
+  external_type: "Post",
+  external_id: post.id,
+  parent: reports
 )
+
+# A grant on the container reaches q3, and every node registered under
+# reports later, as of the next compile!
+SuperAuth::Edge.create(permission: read_perm, resource: reports)
+```
+
+Navigate the tree the same way as groups:
+
+```ruby
+SuperAuth::Resource.roots        # nodes with no parent
+reports.children_dataset.all     # => [q3]
+q3.parent                        # => reports
+```
+
+The compiled row for `q3` carries `q3`'s own `external_type` and `external_id` whether the edge was drawn to `q3` or to `reports`: runtime reads the record a grant reaches and nothing about how it got there. There are no resource path columns in the compiled table; "granted through which container" is a question for the graph (`parent`, `children_dataset`) and the editor.
+
+#### Deprecated: type-level (wildcard) nodes
+
+A node with an `external_type` and no `external_id` is a type-level, or wildcard, node: at runtime it means every record of that type, present and future. `ByCurrentUser` skips per-record filtering when one matches, and the row-level security policy's `resource_external_id IS NULL OR` clause does the same in the database.
+
+```ruby
+# Deprecated: every Post, present and future
+posts = SuperAuth::Resource.create(name: "posts", external_type: "Post")
 ```
 
+Wildcard nodes are deprecated as of 0.8.0 and still work: `compile!` warns once per compile naming the ones that exist (silence it with `SuperAuth.deprecator.silenced = true`, or in Rails through `config.active_support.deprecation`), and no removal version is promised. What `compile!` refuses, with a `SuperAuth::Error` naming the node ids, is a wildcard with a parent or children: nested in the tree it would reach every record of its type through its ancestors' grants. A wildcard stays at the root with no children, or gets an `external_id`.
+
+Under Postgres row-level security a wildcard remains the only way to authorize INSERT this release. The policy is `FOR ALL` with `USING` reused as `WITH CHECK`, and a per-record row can only match an id that has already been registered and compiled. A container is not a replacement for it there: it loses INSERT, it needs a node saved and a full recompile for every new record, and saving that node needs a role that can write the gem's tables, which `enable` grants `SELECT` on only. The successor is a grant on a parent record (`SuperAuth::RLS.enable(:documents, resource_type: "Document", parent: { column: :folder_id, resource_type: "Folder" })`, with a `ByCurrentUser` mirror), planned for the next release.
+
+##### Migrating a wildcard to a container
+
+Where the type is not under row-level security, or INSERT is not needed, a wildcard becomes a container plus one node per record. Move the edges off the wildcard before destroying it, so the grants survive, then compile. `Post` is a `super_auth` model, so its default scope hides every row from a process with no current user — the loop reads through `unscoped`; where RLS is installed the database enforces the same rule, so the work runs as the system user:
+
+```ruby
+wildcard = SuperAuth::Resource.where(external_type: "Post", external_id: nil).first
+
+migrate = proc do
+  container = SuperAuth::Resource.create(name: "posts")            # untyped: a container
+  Post.unscoped.find_each do |post|                                  # ByCurrentUser hides every row without a current user
+    SuperAuth::Resource.create(name: post.title, external_type: "Post", external_id: post.id, parent: container)
+  end
+  SuperAuth::Edge.where(resource_id: wildcard.id).update(resource_id: container.id)  # update_all on the ActiveRecord twin
+  wildcard.destroy
+end
+
+if SuperAuth::RLS.installed?
+  SuperAuth.as(SuperAuth::User.system, &migrate)
+else
+  SuperAuth.db.transaction(&migrate)
+end
+SuperAuth::Authorization.compile!   # SuperAuth::ActiveRecord::Authorization.compile! in Rails
+```
+
+Under row-level security this loses INSERT on `posts` until the parent-record grant exists, and a `Post` created afterwards needs its own node and a recompile before anyone sees it.
+
 ## Drawing Edges
 
 Edges are the core of SuperAuth. Each edge connects exactly two entities.
@@ -311,6 +366,8 @@ SuperAuth automatically evaluates 5 pathing strategies and unions the results. Y
 
 When groups or roles are nested, SuperAuth considers the full tree. If you assign a user to a parent group, they can access resources through roles attached to that group *and all its descendants*.
 
+Resources nest too, at the other end of the path: a grant on a container reaches every node registered under it (see [Resources](#resources-hierarchical)).
+
 ```ruby
 # Bethany is in Company (the root group)
 SuperAuth::Edge.create(user: bethany, group: company)
@@ -349,6 +406,8 @@ auth[:resource_id]      # Integer
 auth[:resource_name]    # "staging"
 ```
 
+`resource_id` and `resource_name` are the node the grant reaches: a row compiled through a container names the descendant, not the container, and there is no resource path column (see [Resources](#resources-hierarchical)).
+
 ### Filter by user
 
 ```ruby
@@ -461,6 +520,8 @@ Post::PostPublishPermission.find(id) # needs a "Post::PostPublishPermission" gra
 
 Approve the subclass like any other resource — register a `SuperAuth::Resource` with `external_type: "Post::PostPublishPermission"` and draw edges to it, then recompile with `SuperAuth::ActiveRecord::Authorization.compile!`.
 
+The resource tree is containment, not inheritance. A row compiled through a container copies the descendant node's own `external_type`, which is why the rule above survives nesting — but a `"Post::PostPublishPermission"` node registered *under* the `"Post"` node is a descendant of it and receives every grant on `"Post"`. Register capability nodes as siblings of their base-class nodes, or in a container beside them, never as their children.
+
 For database-side enforcement of the same rules see "Postgres Row-Level Security" in the README (`SuperAuth::RLS.enable` — visibility is derived automatically from `SuperAuth.current_user`).
 
 ### Linking to your app's models
@@ -475,14 +536,15 @@ sa_user = SuperAuth::User.create(
   external_type: "User"
 )
 
-# Link a SuperAuth resource to your app's Post model
+# Link a SuperAuth resource to one Post
 sa_resource = SuperAuth::Resource.create(
-  name: "posts",
-  external_type: "Post"
+  name: post.title,
+  external_type: "Post",
+  external_id: post.id
 )
 ```
 
-When `super_auth` is included in a model, the default scope matches the current user's `id` and class name against `external_id` / `external_type` in the authorizations table. This means your application user objects work directly -- no need to convert to SuperAuth users in the controller.
+When `super_auth` is included in a model, the default scope matches the current user's `id` and class name against `external_id` / `external_type` in the authorizations table. This means your application user objects work directly -- no need to convert to SuperAuth users in the controller. On the resource side it matches the record's class name and `id` against `resource_external_type` / `resource_external_id`; a node with the type and no id matches every record of the type, the deprecated wildcard shape described under [Resources](#resources-hierarchical).
 
 ### ActiveRecord models
 
@@ -538,9 +600,11 @@ deployers.map { |a| a[:user_name] }.uniq
 ## Visualization
 
 The graph editor shows the whole graph as five boxes (groups, roles, users,
-permissions, resources); click any record to trace what it can reach and what reaches
-it, connect records to draw edges, delete records and edges, and recompile. See the
-README's "Graph editor" section for the full description.
+permissions, resources), drawing groups, roles and resources as trees; click any record
+to trace what it can reach and what reaches it, connect records to draw edges, create
+records (including a resource container under a chosen parent), delete records and
+edges, and recompile. The editor makes containers; your application registers records
+under them. See the README's "Graph editor" section for the full description.
 
 - Rails: mount the engine inside your own authentication (Step 6 above) and open
   `http://localhost:3000/super_auth`.
@@ -577,8 +641,8 @@ write  = SuperAuth::Permission.create(name: "write")
 deploy = SuperAuth::Permission.create(name: "deploy")
 
 # Resources
-api       = SuperAuth::Resource.create(name: "api", external_type: "API")
-dashboard = SuperAuth::Resource.create(name: "dashboard", external_type: "Dashboard")
+api       = SuperAuth::Resource.create(name: "api")
+dashboard = SuperAuth::Resource.create(name: "dashboard")
 prod_db   = SuperAuth::Resource.create(name: "production_db")
 
 # Users
@@ -631,6 +695,7 @@ auths = SuperAuth::Edge.authorizations.all
 | `SuperAuth.current_user`        | Get the current user                                 |
 | `SuperAuth.install_migrations`  | Create all `super_auth_*` tables                     |
 | `SuperAuth.uninstall_migrations`| Drop all `super_auth_*` tables                       |
+| `SuperAuth.deprecator`          | Where deprecation warnings go; `silenced = true` quiets them |
 
 ### Environment Variables
 

data/db/migrate/11_add_parent_id_to_resources.rb

@@ -0,0 +1,32 @@
+Sequel.migration do
+  # Resources nest like groups and roles (2_groups.rb): same integer type as
+  # the pk, deferrable only where supported. The index is skipped on MySQL
+  # for the reason in 8_add_indexes_to_edges.rb — InnoDB indexes the foreign
+  # key column itself and will not drop that index while the constraint
+  # stands. Both branches compute database_type before alter_table: inside
+  # the block self is the generator.
+  up do
+    is_postgres = database_type == :postgres
+    is_mysql = [:mysql, :mysql2].include?(database_type)
+
+    alter_table(:super_auth_resources) do
+      if is_postgres
+        add_foreign_key :parent_id, :super_auth_resources, deferrable: true, type: :integer
+      else
+        add_foreign_key :parent_id, :super_auth_resources, type: :integer
+      end
+      add_index :parent_id unless is_mysql
+    end
+  end
+
+  # drop_foreign_key drops the constraint and then the column; MySQL refuses
+  # to drop a column a constraint still depends on.
+  down do
+    is_mysql = [:mysql, :mysql2].include?(database_type)
+
+    alter_table(:super_auth_resources) do
+      drop_index :parent_id unless is_mysql
+      drop_foreign_key :parent_id
+    end
+  end
+end

data/db/migrate_activerecord/20250101000011_add_parent_id_to_super_auth_resources.rb

@@ -0,0 +1,9 @@
+class AddParentIdToSuperAuthResources < ActiveRecord::Migration[7.0]
+  # Mirrors db/migrate/11_add_parent_id_to_resources.rb. No index on MySQL:
+  # InnoDB indexes the foreign key column itself.
+  def change
+    add_column :super_auth_resources, :parent_id, :bigint
+    add_foreign_key :super_auth_resources, :super_auth_resources, column: :parent_id
+    add_index :super_auth_resources, :parent_id unless connection.adapter_name.match?(/mysql|trilogy/i)
+  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,13 @@ 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 railties: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)
 
 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/super_auth/active_record/authorization.rb

@@ -9,11 +9,18 @@ class SuperAuth::ActiveRecord::Authorization < ActiveRecord::Base
     end
 
     # Clears and repopulates the authorizations table from the current graph.
+    # The wildcard guard runs before the delete, so a refused compile leaves
+    # the previous rows in place; the deprecation notice follows the commit.
     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::Resource.assert_compilable!
         delete_all
         from_graph.each { |auth| create!(auth.attributes.except("id")) }
       end
+      SuperAuth::Resource.warn_deprecated_wildcards
       count
     end
   end

data/lib/super_auth/active_record/resource.rb

@@ -1,6 +1,10 @@
 class SuperAuth::ActiveRecord::Resource < ActiveRecord::Base
   self.table_name = 'super_auth_resources'
   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
@@ -33,10 +37,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 deprecated wildcard — 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/authorization.rb

@@ -4,11 +4,23 @@ class SuperAuth::Authorization < Sequel::Model(:super_auth_authorizations)
   # 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!
-    db.transaction do
+    count = db.transaction do
+      db.run "SET LOCAL jit = off" if db.database_type == :postgres
+      SuperAuth::Resource.assert_compilable!
       dataset.delete
       SuperAuth::Edge.authorizations.each { |row| dataset.insert(row) }
       dataset.count
     end
+    SuperAuth::Resource.warn_deprecated_wildcards
+    count
   end
 end

data/lib/super_auth/edge.rb

@@ -39,6 +39,45 @@ class SuperAuth::Edge < Sequel::Model(:super_auth_edges)
         .union(users_resources)
     end
 
+    # Every resource node a grant reaches: each granted node paired with
+    # itself and each of its descendants, as (ancestor_id, descendant_id).
+    # Anchored on the ids that appear in edges rather than on the whole table.
+    # Groups and roles are few, but resources are one row per protected
+    # record, and the unanchored CTE materialises every pair of the table once
+    # 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.
+    def resource_subtrees
+      granted = db[:super_auth_edges].exclude(resource_id: nil).select(:resource_id)
+      SuperAuth::Resource.descendant_pairs(of: granted)
+    end
+
+    # The last hop of every strategy: from the resource id on an edge to the
+    # node it names and each node under it. The compiled row copies the
+    # descendant's own columns, so containment is not inheritance — a node
+    # keeps its own external_type — and the type-level tricks in ByCurrentUser
+    # still hold. No resource path columns, unlike groups and roles: nothing at
+    # runtime reads one, and super_auth_authorizations gains no columns.
+    def join_resource_subtree(ds, resource_id_column)
+      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.
+        where(
+          Sequel.|(
+            { Sequel[:resource_descendants][:ancestor_id] => Sequel[:resource_descendants][:descendant_id] },
+            { Sequel[:super_auth_resources][:external_type] => nil },
+            Sequel.~(Sequel[:super_auth_resources][:external_id] => nil)
+          )
+        )
+    end
+
     def users_groups_roles_permissions_resources
       cast_type = string_cast_type
       # Join users to their group via edges. group_ancestors pairs that group with itself and
@@ -46,7 +85,7 @@ class SuperAuth::Edge < Sequel::Model(:super_auth_edges)
       # expands the granted role to its whole subtree. Each step is correlated to the previous
       # one, so a role held by one group never reaches members of an unrelated group. The tree
       # CTEs (user_groups, granted_roles) are joined by id only to supply the path columns.
-      SuperAuth::User.db[:super_auth_users].
+      ds = SuperAuth::User.db[:super_auth_users].
         join(Sequel[:super_auth_edges].as(:user_edges), user_id: :id).
         join(SuperAuth::Group.ancestor_pairs.as(:group_ancestors), descendant_id: Sequel[:user_edges][:group_id]).
         join(Sequel[:super_auth_edges].as(:group_role_edges), group_id: Sequel[:group_ancestors][:ancestor_id]).
@@ -56,8 +95,8 @@ class SuperAuth::Edge < Sequel::Model(:super_auth_edges)
         join(SuperAuth::Role.from(SuperAuth::Role.trees).as(:granted_roles), Sequel[:granted_roles][:id] => Sequel[:role_descendants][:descendant_id]).
         join(Sequel[:super_auth_edges].as(:permission_edges), Sequel[:permission_edges][:role_id] => Sequel[:granted_roles][:id]).
         join(Sequel[:super_auth_permissions], id: Sequel[:permission_edges][:permission_id]).
-        join(Sequel[:super_auth_edges].as(:resource_edges), Sequel[:resource_edges][:permission_id] => Sequel[:super_auth_permissions][:id]).
-        join(Sequel[:super_auth_resources], id: Sequel[:resource_edges][:resource_id]).
+        join(Sequel[:super_auth_edges].as(:resource_edges), Sequel[:resource_edges][:permission_id] => Sequel[:super_auth_permissions][:id])
+      join_resource_subtree(ds, Sequel[:resource_edges][:resource_id]).
         select(
           Sequel[:super_auth_users][:id].as(:user_id),
           Sequel[:super_auth_users][:name].as(:user_name),
@@ -100,14 +139,14 @@ class SuperAuth::Edge < Sequel::Model(:super_auth_edges)
       # Join users to their group via edges. group_ancestors pairs that group with itself and
       # every ancestor, so a group -> permission edge on any of them applies. user_groups (the
       # tree) is joined by id only to supply the path columns.
-      SuperAuth::User.db[:super_auth_users].
+      ds = SuperAuth::User.db[:super_auth_users].
         join(Sequel[:super_auth_edges].as(:user_edges), user_id: :id).
         join(SuperAuth::Group.ancestor_pairs.as(:group_ancestors), descendant_id: Sequel[:user_edges][:group_id]).
         join(Sequel[:super_auth_edges].as(:group_edges), group_id: Sequel[:group_ancestors][:ancestor_id]).
         join(SuperAuth::Group.from(SuperAuth::Group.trees).as(:user_groups), Sequel[:user_groups][:id] => Sequel[:user_edges][:group_id]).
         join(Sequel[:super_auth_permissions], id: Sequel[:group_edges][:permission_id]).
-        join(Sequel[:super_auth_edges].as(:permission_edges), Sequel[:permission_edges][:permission_id] => Sequel[:super_auth_permissions][:id]).
-        join(Sequel[:super_auth_resources], id: Sequel[:permission_edges][:resource_id]).
+        join(Sequel[:super_auth_edges].as(:permission_edges), Sequel[:permission_edges][:permission_id] => Sequel[:super_auth_permissions][:id])
+      join_resource_subtree(ds, Sequel[:permission_edges][:resource_id]).
         select(
           Sequel[:super_auth_users][:id].as(:user_id),
           Sequel[:super_auth_users][:name].as(:user_name),
@@ -150,7 +189,7 @@ class SuperAuth::Edge < Sequel::Model(:super_auth_edges)
 
       # Join users to the roles they hold directly. role_descendants expands each held role to
       # its whole subtree; granted_roles (the tree) is joined by id only to supply the path columns.
-      SuperAuth::User.db[:super_auth_users].
+      ds = SuperAuth::User.db[:super_auth_users].
       join(Sequel[:super_auth_edges].as(:user_edges), user_id: :id).
       where(Sequel.~(Sequel[:user_edges][:role_id] => nil)).
       join(SuperAuth::Role.descendant_pairs.as(:role_descendants), ancestor_id: Sequel[:user_edges][:role_id]).
@@ -192,14 +231,13 @@ class SuperAuth::Edge < Sequel::Model(:super_auth_edges)
       # Join permission and resource edges on the expanded role
       join(Sequel[:super_auth_edges].as(:permission_edges), Sequel[:permission_edges][:role_id] => Sequel[:granted_roles][:id]).
       join(Sequel[:super_auth_permissions], id: Sequel[:permission_edges][:permission_id]).
-      join(Sequel[:super_auth_edges].as(:resource_edges), Sequel[:resource_edges][:permission_id] => Sequel[:super_auth_permissions][:id]).
-      join(Sequel[:super_auth_resources], id: Sequel[:resource_edges][:resource_id]).
-      distinct
+      join(Sequel[:super_auth_edges].as(:resource_edges), Sequel[:resource_edges][:permission_id] => Sequel[:super_auth_permissions][:id])
+      join_resource_subtree(ds, Sequel[:resource_edges][:resource_id]).distinct
     end
 
     def users_permissions_resources
       cast_type = string_cast_type
-      SuperAuth::User.
+      ds = SuperAuth::User.
         join(Sequel[:super_auth_edges].as(:user_edges), user_id: :id).
         select(
           Sequel[:super_auth_users][:id].as(:user_id),
@@ -237,14 +275,13 @@ class SuperAuth::Edge < Sequel::Model(:super_auth_edges)
         ).
       join(Sequel[:super_auth_edges].as(:permission_edges), Sequel[:permission_edges][:user_id] => Sequel[:super_auth_users][:id]).
       join(Sequel[:super_auth_permissions], id: Sequel[:permission_edges][:permission_id]).
-      join(Sequel[:super_auth_edges].as(:resource_edges), Sequel[:resource_edges][:permission_id] => Sequel[:super_auth_permissions][:id]).
-      join(Sequel[:super_auth_resources], id: Sequel[:resource_edges][:resource_id]).
-      distinct
+      join(Sequel[:super_auth_edges].as(:resource_edges), Sequel[:resource_edges][:permission_id] => Sequel[:super_auth_permissions][:id])
+      join_resource_subtree(ds, Sequel[:resource_edges][:resource_id]).distinct
     end
 
     def users_resources
       cast_type = string_cast_type
-      SuperAuth::User.
+      ds = SuperAuth::User.
         join(Sequel[:super_auth_edges].as(:user_edges), user_id: :id).
         select(
           Sequel[:super_auth_users][:id].as(:user_id),
@@ -279,9 +316,8 @@ class SuperAuth::Edge < Sequel::Model(:super_auth_edges)
           Sequel[:super_auth_resources][:name].as(:resource_name),
           Sequel[:super_auth_resources][:external_id].as(:resource_external_id),
           Sequel[:super_auth_resources][:external_type].as(:resource_external_type)
-        ).
-      join(Sequel[:super_auth_resources], Sequel[:user_edges][:resource_id] => Sequel[:super_auth_resources][:id]).
-      distinct
+        )
+      join_resource_subtree(ds, Sequel[:user_edges][:resource_id]).distinct
     end
   end
 

data/lib/super_auth/editor/index.html

@@ -53,8 +53,8 @@
   .region{display:grid;gap:10px;min-height:0}
   .region.top{flex:1.15;grid-template-columns:1fr 1fr;grid-template-rows:1fr 1fr;
     grid-template-areas:"group role" "user perm"}
-  .region.bottom{flex:.85;grid-template-columns:1fr 1fr;grid-template-rows:1fr;
-    grid-template-areas:"resource user2"}
+  .region.bottom{flex:.85;grid-template-columns:1fr;grid-template-rows:1fr;
+    grid-template-areas:"resource"}
 
   /* ---- box ---- */
   .box{background:var(--panel);border:1px solid var(--line);border-radius:10px;display:flex;flex-direction:column;min-height:0;overflow:hidden}
@@ -63,7 +63,6 @@
   .box[data-area=user]{grid-area:user;--accent:var(--c-user)}
   .box[data-area=permission]{grid-area:perm;--accent:var(--c-perm)}
   .box[data-area=resource]{grid-area:resource;--accent:var(--c-resource)}
-  .box[data-area=user2]{grid-area:user2;--accent:var(--c-user)}
   .box-head{display:flex;align-items:center;gap:9px;padding:9px 12px;border-bottom:1px solid var(--line);flex:none}
   .box-head .swatch{width:10px;height:10px;border-radius:3px;background:var(--accent);flex:none;box-shadow:0 0 10px -2px var(--accent)}
   .box-head .title{font-family:var(--mono);font-weight:600;font-size:13px;letter-spacing:.02em}
@@ -122,7 +121,6 @@
   </section>
   <section class="region bottom">
     <div class="box" data-area="resource" data-type="resource"></div>
-    <div class="box" data-area="user2"     data-type="user"></div>
   </section>
 </main>
 
@@ -130,7 +128,7 @@
 // The app may be mounted under a prefix; every API call is relative to this page.
 const API = location.pathname.replace(/\/$/, "");
 const TITLES = {group:"Groups", role:"Roles", user:"Users", permission:"Permissions", resource:"Resources"};
-const NESTED = new Set(["group","role"]);
+const NESTED = new Set(["group","role","resource"]);
 
 let GRAPH = null;           // {groups,roles,users,permissions,resources,edges,authorizations_count}
 let selection = null;       // {type,id}
@@ -157,8 +155,8 @@ async function load(){
 // Authorization flows user → group → role → permission → resource. From the
 // selected node we collect everything DOWNSTREAM (what it can reach) and
 // everything UPSTREAM (what can reach it). So a user shows what they can access;
-// a resource shows who can access it. Group/role hierarchy is bidirectional
-// (a parent's grants apply to children, and a parent "contains" its children).
+// a resource shows who can access it. The group, role and resource trees are
+// each folded in as one more directed hop (see buildDirected).
 const RANK = {user:0, group:1, role:2, permission:3, resource:4};
 
 function buildDirected(){
@@ -184,9 +182,13 @@ function buildDirected(){
   //    inherits ANCESTOR grants → a child group is upstream of its parent.
   //  • Role grants flow to DESCENDANT roles, so holding a parent role includes
   //    its children → a parent role is upstream of its child.
+  //  • Resource grants reach DESCENDANT resources: a grant on a container
+  //    covers everything under it → a parent resource is upstream of its
+  //    children, the same direction as roles and the opposite of groups.
   // (Selecting a child group therefore reaches its ancestors, never its siblings.)
   for(const g of GRAPH.groups) if(g.parent_id) dir(key("group",g.id), key("group",g.parent_id));
   for(const r of GRAPH.roles)  if(r.parent_id) dir(key("role",r.parent_id), key("role",r.id));
+  for(const r of GRAPH.resources) if(r.parent_id) dir(key("resource",r.parent_id), key("resource",r.id));
   return {fwd,bwd};
 }
 
@@ -248,11 +250,16 @@ function render(){
       const name = n.name ?? "";
       // 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.
+      // 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.
+      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 ext = !ref ? "" : (n.super_auth_label
-        ? `<span class="ext" title="${ref}">${escapeHtml(n.super_auth_label)}</span>`
-        : `<span class="ext" title="external record">${ref}</span>`);
+        ? `<span class="ext" title="${wildcard ? `${ref} · ${kind}` : ref}">${escapeHtml(n.super_auth_label)}</span>`
+        : `<span class="ext" title="${kind}">${ref}</span>`);
       return `<div class="item ${isSel?'selected':''} ${isCF?'connect-first':''}" data-id="${n.id}" ${pad}>
         <span class="tick"></span>
         ${arrow}<span class="name" title="${escapeHtml(name)}">${escapeHtml(name)}</span>${ext}

data/lib/super_auth/editor/seed.rb

@@ -15,6 +15,11 @@ module SuperAuth
     #     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
@@ -68,8 +73,9 @@ module SuperAuth
 
           # ===== RESOURCES (disjoint per department) =====
           source_repo        = res_m.create(name: "source_repo")
-          production_cluster = res_m.create(name: "production_cluster")
-          staging_cluster    = res_m.create(name: "staging_cluster")
+          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")
@@ -99,8 +105,8 @@ module SuperAuth
           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)
-          edg.create(permission_id: deploy.id,     resource_id: production_cluster.id)
-          edg.create(permission_id: deploy.id,     resource_id: staging_cluster.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)
@@ -153,7 +159,7 @@ module SuperAuth
       def clear!
         SuperAuth::Edge.dataset.delete
         SuperAuth::Authorization.dataset.delete
-        [SuperAuth::Group, SuperAuth::Role].each { |m| m.dataset.update(parent_id: nil) }
+        [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

data/lib/super_auth/editor.rb

@@ -3,7 +3,8 @@ require "super_auth"
 
 module SuperAuth
   # A small Rack application that edits the authorization graph: five boxes of
-  # records, client-side traversal, node and edge CRUD, and a Recompile button.
+  # 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
@@ -19,7 +20,9 @@ module SuperAuth
   #
   # 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.
+  # 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,
@@ -29,7 +32,7 @@ module SuperAuth
       "user" => :user_id, "group" => :group_id, "role" => :role_id,
       "permission" => :permission_id, "resource" => :resource_id,
     }.freeze
-    NESTED = %w[group role].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.
@@ -69,6 +72,8 @@ module SuperAuth
       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
@@ -103,7 +108,7 @@ module SuperAuth
         roles: nodes(:Role, :parent_id),
         users: nodes(:User, :external_id, :external_type),
         permissions: nodes(:Permission),
-        resources: nodes(:Resource, :external_id, :external_type, :super_auth_label),
+        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,
       }
@@ -122,9 +127,12 @@ module SuperAuth
     # 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, id] pairs, outermost first, puts every child under its
-    # own parent and leaves siblings alphabetical. Both node sets are small
-    # enough to order in Ruby, and the client's depthOf is unaffected.
+    # 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
@@ -137,7 +145,7 @@ module SuperAuth
         node = row
         while node && !seen[node[:id]]
           seen[node[:id]] = true
-          path.unshift([node[:name].to_s, node[:id]])
+          path.unshift([node[:name].to_s, node[:super_auth_label].to_s, node[:id]])
           node = by_id[node[:parent_id]]
         end
         path
@@ -158,7 +166,14 @@ module SuperAuth
       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)
-        return json(422, error: "parent not found") unless model[parent.to_i]
+        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
 

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

@@ -16,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

data/lib/super_auth/version.rb

@@ -1,3 +1,3 @@
 module SuperAuth
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

data/lib/super_auth.rb

@@ -4,10 +4,41 @@ require "sequel"
 module SuperAuth
   class Error < StandardError; end
 
+  # Stand-in for ActiveSupport::Deprecation when ActiveSupport is not loaded:
+  # the same two methods the gem calls. Plain Kernel.warn rather than
+  # `category: :deprecated`, which Ruby hides unless -W:deprecated is set,
+  # and a warning nobody sees is not a deprecation.
+  class Deprecator
+    attr_accessor :silenced
+
+    def warn(message)
+      return if silenced
+      Kernel.warn "DEPRECATION WARNING: #{message}"
+    end
+  end
+
   def self.setup
     yield self if block_given?
   end
 
+  # Where the gem's deprecation warnings go. An ActiveSupport::Deprecation
+  # when ActiveSupport is loaded, so a Rails host's
+  # config.active_support.deprecation applies once the railtie registers it
+  # under app.deprecators; otherwise the stand-in above. Both answer
+  # `silenced = true`. Memoized, so that setting survives.
+  def self.deprecator
+    @deprecator ||=
+      if defined?(ActiveSupport::Deprecation)
+        ActiveSupport::Deprecation.new("1.0", "SuperAuth")
+      else
+        Deprecator.new
+      end
+  end
+
+  def self.deprecator=(deprecator)
+    @deprecator = deprecator
+  end
+
   # Controls behavior when SuperAuth.current_user is blank in ByCurrentUser scope.
   # :none (default) — returns an empty result set silently
   # :raise — raises SuperAuth::Error

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: super_auth
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Jonathan Frias
@@ -56,6 +56,7 @@ files:
 - USAGE.md
 - config/routes.rb
 - db/migrate/10_add_super_auth_label_to_resources.rb
+- db/migrate/11_add_parent_id_to_resources.rb
 - db/migrate/1_users.rb
 - db/migrate/2_groups.rb
 - db/migrate/3_permissions.rb
@@ -74,6 +75,7 @@ files:
 - db/migrate_activerecord/20250101000007_create_super_auth_authorizations.rb
 - db/migrate_activerecord/20250101000009_add_by_current_user_index_to_super_auth_authorizations.rb
 - db/migrate_activerecord/20250101000010_add_super_auth_label_to_super_auth_resources.rb
+- db/migrate_activerecord/20250101000011_add_parent_id_to_super_auth_resources.rb
 - db/seeds/sample_data.rb
 - exe/super_auth-editor
 - lib/basic_loader.rb